From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mail-io1-f47.google.com (mail-io1-f47.google.com [209.85.166.47]) by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id 9f0ff2d8 for ; Fri, 14 Jun 2019 03:16:30 -0500 (EST) Received: by mail-io1-f47.google.com with SMTP id k13so3917042iop.5 for ; Fri, 14 Jun 2019 01:16:29 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=mime-version:from:date:message-id:subject:to; bh=xVkfg/aX+H73Lm1rDE2WsjrcQ/S8EA3SblDfcxkefb8=; b=ab2XCJenr5KxiJNsZ+poIdNRvribC/ZC4sRjMKVMgxeKhaPKiTc4QDXGCfqUFIPBXr c5v2bKeLsZIdt9GZeoeM0499NBW2JyXUFCL08I5AVZ2BCrkLdQ/Rr/Z/uG1w5CWH7spj WsY1Rgqt4Ro/0wto3bvHM+0Mwl4s0cC9R28JdsklSCid+jjJH1/a2fvL1LQ/JVUDc7VS a8EgjwTlhBCekrcNgpUUxVYQd/In3D3Q2QLvMFbHG4vAgAaMGP48idHxWJ2Esox8opCL er9kHbZyUxSbVVTR/hDkR+Ro2HuUzxnZG4lbdxFEoba7h5xh+yC892isKP4eYEJ/FFyw BJkw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:from:date:message-id:subject:to; bh=xVkfg/aX+H73Lm1rDE2WsjrcQ/S8EA3SblDfcxkefb8=; b=qInqlC/lApIql3Sz0wttqkeH8ArenLgqdE2TnJ655p+VVdu8G4hfKR3daaIJyyljF1 OVSzLUdF536YPq2cqnMcrLUQ8ysOg374NbRfTOLucl6sMx2R+U6sPLS4qQRtPR6Lsvil oBSGF27HFFYMdgwabc7gvPJB0GY9rS9Er6HQ3VHmHa/0P89kjXXyZDTkZTiZUEcmfybg a8d5/wd6WRGEYE+QAclNQnoHLI4slmAEHg3VWZR4Utjifiwn4XBvo1XxNCgedAYNa23h 7OkBFDQNfJH72KfM3kvOm5QpReCQM2UkUL39ZPv5Fe/iO/rjLeNkEtBmaeMtOwDzftSE YVpw== X-Gm-Message-State: APjAAAWFqWDleSPztcZsNUk0hLB7DjLUhO7JZ/CB38R0D+NDJfgl6aRn 2uuT6ilShqDFJQIJmlKHgJQ5F2zntNxkofkR6w8mP8Kc X-Google-Smtp-Source: APXvYqzNEl6g5kBi+ihHRsvNhFK9PdNGyHMF+vBOwSZQBXBDFiJGB1qywUGJMhM7HZKAtPmADLJ53uDbNGwHpRRn9t8= X-Received: by 2002:a5d:9d42:: with SMTP id k2mr35019428iok.45.1560500188742; Fri, 14 Jun 2019 01:16:28 -0700 (PDT) X-Mailinglist: mandoc-discuss Reply-To: discuss@mandoc.bsd.lv MIME-Version: 1.0 From: Matthew Singletary Date: Fri, 14 Jun 2019 04:16:17 -0400 Message-ID: Subject: Mandoc for oil To: discuss@mandoc.bsd.lv Content-Type: multipart/alternative; boundary="0000000000006c0c64058b4443e2" --0000000000006c0c64058b4443e2 Content-Type: text/plain; charset="UTF-8" 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 --0000000000006c0c64058b4443e2 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
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 m= an page before but thought I'd try to use some decent tools to start wi= th.

I'm a little confused about distributi= on/workflow for distributing man pages (in general). If osh.1 is an mdoc fl= avored file, would that be used (with mandoc -T man) to output a man page t= hat 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 generati= ng/installing the man pages on the manpath?

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

Thanks,
Matt
--0000000000006c0c64058b4443e2-- -- To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mx.stare.cz (mx.stare.cz [79.98.77.229]) by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id f9f6ba44 for ; Fri, 14 Jun 2019 03:43:15 -0500 (EST) Received: from www.stare.cz (localhost [127.0.0.1]) by www.stare.cz (OpenSMTPD) with ESMTP id 9817a3a8 for ; Fri, 14 Jun 2019 10:43:13 +0200 (CEST) Date: Fri, 14 Jun 2019 10:43:13 +0200 From: Jan Stary To: discuss@mandoc.bsd.lv Subject: Re: Mandoc for oil Message-ID: <20190614084313.GA17405@www.stare.cz> References: X-Mailinglist: mandoc-discuss Reply-To: discuss@mandoc.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: User-Agent: Mutt/1.7.1 (2016-10-04) 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 From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mx.stare.cz (ns.stare.cz [79.98.77.229]) by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id 913898e3 for ; Fri, 14 Jun 2019 03:54:24 -0500 (EST) Received: from www.stare.cz (localhost [127.0.0.1]) by www.stare.cz (OpenSMTPD) with ESMTP id 6d449f3d for ; Fri, 14 Jun 2019 10:54:23 +0200 (CEST) Date: Fri, 14 Jun 2019 10:54:23 +0200 From: Jan Stary To: discuss@mandoc.bsd.lv Subject: Re: Mandoc for oil Message-ID: <20190614085423.GC17405@www.stare.cz> References: <20190614084313.GA17405@www.stare.cz> X-Mailinglist: mandoc-discuss Reply-To: discuss@mandoc.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20190614084313.GA17405@www.stare.cz> User-Agent: Mutt/1.7.1 (2016-10-04) > 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 From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mail-io1-f46.google.com (mail-io1-f46.google.com [209.85.166.46]) by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id b1fc85fa for ; Fri, 14 Jun 2019 04:24:36 -0500 (EST) Received: by mail-io1-f46.google.com with SMTP id n5so4236907ioc.7 for ; Fri, 14 Jun 2019 02:24:36 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=mime-version:references:in-reply-to:from:date:message-id:subject:to; bh=Yv6UWblOpOqUIRl87aDIPkTzwBjOisBTYEjBQkc+5/I=; b=o9k/HaC/JTk5bLthaQctXqedW3d3vG/eY4FsVON7n9LT0p/Rw2wUqnLOBOmOFmnkAS WuuWGCUnXd1RzUbTxVcajWOuUgRmCMrW776WN51lp8+YYgdTgeVMkEUAmna8IdnUm0GK rNh7SmvrtKq9Cm0KvohRGqKkvaq9KqJBWYbgZBEz0G5YsUFuNm2qCdNQfh7XlA/EQqPS KJyYbiHwO+N3grzyLomAkQOBpSeI/iUezyXV7wPDYMwlZ8u0aD3gUwRTJj5LUNK1y+/C D7P980QVv39/9EVZyRTWOlS/iAbb4QguhPdjh8jdxiztO2f93nX9uSIkHtZBlAJ+ufzr CBoA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to; bh=Yv6UWblOpOqUIRl87aDIPkTzwBjOisBTYEjBQkc+5/I=; b=TgppvRNLPHHWmds2WYwWqjFaw1Nxd0UcCYlO1V+wKBA5B81w9iP0kHqSbMmL0Dxvhs uBu1yS8mPDddDcjGwIwswTdfgJvWLw5RXtK+HcK0S3mXV3Edc+HglsD3qn4O4jsOqMN1 1fARhSQp8KeguNfV+SvaTXI+XeSqbNTszv5cKioJ6aB3tE+CpjWcWGEP/VfLxloicPud qjCLycFIdTF1N8zOWMMXH4tHSZVTsuqegm2XGhYvK3JzIe/zA8w7zMijEmp5GuDxiKRz 1uXtlY0XzFbfkgw0BJ5JRhJDd5Id2dLvzaRFuf2kB4U6XajaVeaLBiPwLsvHgLiZwafu DtCA== X-Gm-Message-State: APjAAAWUryfd6cD2UECwINvqztiyKNMNnEUHriETwi0NyJOL6g9Rp9I5 W9SV3YeyNzFtemnMYBA7zK4ctIFEQN7V768m57MJ3w== X-Google-Smtp-Source: APXvYqyR4ZyWls4vppIDfDCckE3xKr57gFo7fptCDs8knI6hB0x6aHmkhoBzcqF/0gKQB6L/H+Xztl9d6GpCLaW6fXw= X-Received: by 2002:a02:5b88:: with SMTP id g130mr65637099jab.16.1560504275502; Fri, 14 Jun 2019 02:24:35 -0700 (PDT) X-Mailinglist: mandoc-discuss Reply-To: discuss@mandoc.bsd.lv MIME-Version: 1.0 References: <20190614084313.GA17405@www.stare.cz> <20190614085423.GC17405@www.stare.cz> In-Reply-To: <20190614085423.GC17405@www.stare.cz> From: Matthew Singletary Date: Fri, 14 Jun 2019 05:24:23 -0400 Message-ID: Subject: Re: Mandoc for oil To: discuss@mandoc.bsd.lv Content-Type: multipart/alternative; boundary="000000000000030c24058b453790" --000000000000030c24058b453790 Content-Type: text/plain; charset="UTF-8" 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 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 > > --000000000000030c24058b453790 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
Jan,
=C2=A0Thanks for the reply.
= =C2=A0 I was concerned that if I wrote osh.1 in mdoc(7), I would need to ge= nerate another man(7) page for systems that don't support mdoc(7), ie m= ost linuxes. But isn't the point of mandoc -T man to output man(7) from= an mdoc(7) file?t don't
=C2=A0 Or asking another way; w= hat'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) (i= e most linuxes)?

=C2=A0Sorry if I'm being uncl= ear and thanks for your help.



=
On Fri, Ju= n 14, 2019 at 4:54 AM Jan Stary <hans@s= tare.cz> wrote:
> mdoc(5) is just a format;

I mean mdoc(7), sorry.

> A good start is
>
>=C2=A0 =C2=A0 =C2=A0 =C2=A0$ 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
>
>=C2=A0 =C2=A0 =C2=A0 =C2=A0$ 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.

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

Jan

--
=C2=A0To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv
--000000000000030c24058b453790-- -- To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mail.sgregoratto.me (mail.sgregoratto.me [149.28.166.45]) by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id 085cc02e for ; Fri, 14 Jun 2019 04:54:09 -0500 (EST) Received: from mail.sgregoratto.me (localhost [127.0.0.1]) by mail.sgregoratto.me (Postfix) with ESMTP id 190A93EB4D for ; Fri, 14 Jun 2019 19:54:07 +1000 (AEST) Authentication-Results: mail.sgregoratto.me (amavisd-new); dkim=pass (1024-bit key) reason="pass (just generated, assumed good)" header.d=sgregoratto.me DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=sgregoratto.me; h=user-agent:in-reply-to:content-disposition:content-type :content-type:mime-version:references:message-id:subject:subject :to:from:from:date:date; s=dkim; t=1560506046; x=1563098047; bh= x00hiqjREDj/fJjOucCl3o17U09PDv+FCxNQscUKpVY=; b=PqLw5YWls2vK3h0U ILSItjuTf9N47Rtgc9oGzxAb/IhWav+lIKX9TnAHk3y0CN859QA8/JJl+T32pJZD 32vmKQklfOJyEkM4vXTno1Uim1HkB79qVz+kHDYhmN0m89SLdwW9Ao1gN1cD3DOX lIiHCbEqGd1LBY27PZMckqD5HPk= X-Virus-Scanned: Debian amavisd-new at mail.sgregoratto.me Received: from mail.sgregoratto.me ([127.0.0.1]) by mail.sgregoratto.me (mail.sgregoratto.me [127.0.0.1]) (amavisd-new, port 10026) with ESMTP id W8HCrQdGbR6K for ; Fri, 14 Jun 2019 19:54:06 +1000 (AEST) Received: from localhost (172.44.179.58.sta.dodo.net.au [58.179.44.172]) by mail.sgregoratto.me (Postfix) with ESMTPSA id 60CF33E8C2 for ; Fri, 14 Jun 2019 19:54:06 +1000 (AEST) Date: Fri, 14 Jun 2019 19:54:05 +1000 From: Stephen Gregoratto To: discuss@mandoc.bsd.lv Subject: Re: Mandoc for oil Message-ID: <20190614095405.qtqxhqmu5yq6m3ib@BlackBox> Mail-Followup-To: discuss@mandoc.bsd.lv References: X-Mailinglist: mandoc-discuss Reply-To: discuss@mandoc.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Disposition: inline In-Reply-To: User-Agent: NeoMutt/20180716 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 From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mx.stare.cz (mx.stare.cz [79.98.77.229]) by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id b44c001d for ; Fri, 14 Jun 2019 06:40:08 -0500 (EST) Received: from www.stare.cz (localhost [127.0.0.1]) by www.stare.cz (OpenSMTPD) with ESMTP id 4b5a9412 for ; Fri, 14 Jun 2019 13:40:07 +0200 (CEST) Date: Fri, 14 Jun 2019 13:40:07 +0200 From: Jan Stary To: discuss@mandoc.bsd.lv Subject: Re: Mandoc for oil Message-ID: <20190614114006.GB77287@www.stare.cz> References: <20190614084313.GA17405@www.stare.cz> <20190614085423.GC17405@www.stare.cz> X-Mailinglist: mandoc-discuss Reply-To: discuss@mandoc.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: User-Agent: Mutt/1.7.1 (2016-10-04) 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 From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mx.stare.cz (mx.stare.cz [79.98.77.229]) by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id f78fa808 for ; Fri, 14 Jun 2019 07:03:49 -0500 (EST) Received: from www.stare.cz (localhost [127.0.0.1]) by www.stare.cz (OpenSMTPD) with ESMTP id 7cde0129 for ; Fri, 14 Jun 2019 14:03:48 +0200 (CEST) Date: Fri, 14 Jun 2019 14:03:48 +0200 From: Jan Stary To: discuss@mandoc.bsd.lv Subject: Re: Mandoc for oil Message-ID: <20190614120348.GC77287@www.stare.cz> References: <20190614095405.qtqxhqmu5yq6m3ib@BlackBox> X-Mailinglist: mandoc-discuss Reply-To: discuss@mandoc.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20190614095405.qtqxhqmu5yq6m3ib@BlackBox> User-Agent: Mutt/1.7.1 (2016-10-04) > 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 From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from scc-mailout-kit-01.scc.kit.edu (scc-mailout-kit-01.scc.kit.edu [129.13.231.81]) by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id 4b98b871 for ; Fri, 14 Jun 2019 07:29:45 -0500 (EST) Received: from asta-nat.asta.uni-karlsruhe.de ([172.22.63.82] helo=hekate.usta.de) by scc-mailout-kit-01.scc.kit.edu with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (envelope-from ) id 1hblKw-0006jM-Tv; Fri, 14 Jun 2019 14:29:44 +0200 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.77) (envelope-from ) id 1hblKw-00063Y-1A; Fri, 14 Jun 2019 14:29:42 +0200 Received: from athene.usta.de ([172.24.96.10]) by donnerwolke.usta.de with esmtp (Exim 4.84_2) (envelope-from ) id 1hblKv-0006DB-Ik; Fri, 14 Jun 2019 14:29:41 +0200 Received: from localhost (athene.usta.de [local]) by athene.usta.de (OpenSMTPD) with ESMTPA id 938044b6; Fri, 14 Jun 2019 14:29:41 +0200 (CEST) Date: Fri, 14 Jun 2019 14:29:41 +0200 From: Ingo Schwarze To: discuss@mandoc.bsd.lv Cc: Matthew Singletary Subject: Re: Mandoc for oil Message-ID: <20190614122941.GB25099@athene.usta.de> References: <20190614084313.GA17405@www.stare.cz> <20190614085423.GC17405@www.stare.cz> X-Mailinglist: mandoc-discuss Reply-To: discuss@mandoc.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: User-Agent: Mutt/1.8.0 (2017-02-23) 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 From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mx.stare.cz (mx.stare.cz [79.98.77.229]) by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id 1ae2c77b for ; Fri, 14 Jun 2019 08:08:33 -0500 (EST) Received: from www.stare.cz (localhost [127.0.0.1]) by www.stare.cz (OpenSMTPD) with ESMTP id b27787c3 for ; Fri, 14 Jun 2019 15:08:32 +0200 (CEST) Date: Fri, 14 Jun 2019 15:08:32 +0200 From: Jan Stary To: discuss@mandoc.bsd.lv Subject: Re: Mandoc for oil Message-ID: <20190614130830.GB1441@www.stare.cz> References: <20190614084313.GA17405@www.stare.cz> <20190614085423.GC17405@www.stare.cz> <20190614122941.GB25099@athene.usta.de> X-Mailinglist: mandoc-discuss Reply-To: discuss@mandoc.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20190614122941.GB25099@athene.usta.de> User-Agent: Mutt/1.7.1 (2016-10-04) > > 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 From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mx.stare.cz (ns.stare.cz [79.98.77.229]) by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id 27e8a1c4 for ; Fri, 14 Jun 2019 09:27:16 -0500 (EST) Received: from www.stare.cz (localhost [127.0.0.1]) by www.stare.cz (OpenSMTPD) with ESMTP id 36868f66 for ; Fri, 14 Jun 2019 16:27:14 +0200 (CEST) Date: Fri, 14 Jun 2019 16:27:14 +0200 From: Jan Stary To: discuss@mandoc.bsd.lv Subject: Re: Mandoc for oil Message-ID: <20190614142714.GA34987@www.stare.cz> References: <20190614084313.GA17405@www.stare.cz> <20190614085423.GC17405@www.stare.cz> <20190614122941.GB25099@athene.usta.de> X-Mailinglist: mandoc-discuss Reply-To: discuss@mandoc.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20190614122941.GB25099@athene.usta.de> User-Agent: Mutt/1.7.1 (2016-10-04) 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 From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from scc-mailout-kit-01.scc.kit.edu (scc-mailout-kit-01.scc.kit.edu [129.13.231.81]) by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id be295674 for ; Fri, 14 Jun 2019 09:54:17 -0500 (EST) Received: from asta-nat.asta.uni-karlsruhe.de ([172.22.63.82] helo=hekate.usta.de) by scc-mailout-kit-01.scc.kit.edu with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (envelope-from ) id 1hbnap-0000Hp-OP; Fri, 14 Jun 2019 16:54:17 +0200 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.77) (envelope-from ) id 1hbnap-0006rb-6u; Fri, 14 Jun 2019 16:54:15 +0200 Received: from athene.usta.de ([172.24.96.10]) by donnerwolke.usta.de with esmtp (Exim 4.84_2) (envelope-from ) id 1hbnap-0006nc-4g; Fri, 14 Jun 2019 16:54:15 +0200 Received: from localhost (athene.usta.de [local]) by athene.usta.de (OpenSMTPD) with ESMTPA id 3f2aa147; Fri, 14 Jun 2019 16:54:15 +0200 (CEST) Date: Fri, 14 Jun 2019 16:54:15 +0200 From: Ingo Schwarze To: Jan Stary Cc: discuss@mandoc.bsd.lv Subject: Re: Mandoc for oil Message-ID: <20190614145415.GE25099@athene.usta.de> References: <20190614084313.GA17405@www.stare.cz> <20190614085423.GC17405@www.stare.cz> <20190614122941.GB25099@athene.usta.de> <20190614142714.GA34987@www.stare.cz> X-Mailinglist: mandoc-discuss Reply-To: discuss@mandoc.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20190614142714.GA34987@www.stare.cz> User-Agent: Mutt/1.8.0 (2017-02-23) 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 From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mail-io1-f66.google.com (mail-io1-f66.google.com [209.85.166.66]) by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id 34b0f0a4 for ; Sat, 15 Jun 2019 21:40:08 -0500 (EST) Received: by mail-io1-f66.google.com with SMTP id e5so14143858iok.4 for ; Sat, 15 Jun 2019 19:40:08 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=mime-version:references:in-reply-to:from:date:message-id:subject:to; bh=g0GPjWhxm0zoGrN3qwQb3MfsUUbmYUpEqA71hQ2kG6w=; b=PS5piKxjM3q4Nmm4FoUodKPrwjxDqkmdpBqK0pGvEN3wfyA7+NnhQxHmTCIOxlSyCB EOk0KtRK1DD46ZbMyhZf+OhuIZLqof70g+yV01ZAGp9OxHba/+bXBToXb3i+OQHGbWNR me2oVe7w3GRFZDnlyaYLv+XpfquONIinNrhzWOWdd30Oeo6ZNM8nqyN9/v6RjIhEotft iV4I/LWa8EiNV8b/iTR5ZIUQKa3AtsTqIG+dUD97DhJ9WBp56P8bLfIEtGHW+DBqglLY vTS55HrG/KVvNibPegRK0l9A50IhyZL/WH7g4XpIzjQESQELtmyshMBAV+bLuKuXJ4EV 368w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to; bh=g0GPjWhxm0zoGrN3qwQb3MfsUUbmYUpEqA71hQ2kG6w=; b=ama7LttfhMY+FD6UE86iN1T48EDMgnlv1K0fh/6Zv/fjcygvzqgFGzUHDw7JnczCqh jp+6Lmp5KCfiy0cpcGLOLb5Md5LHPH+tbC57To76/5XsI7Nj6qUwd34TQQa0gV+pmB/o VA2yc23rvTRAcDQnMxlWzVRJNr6NEkXWKs7VSedqqthxSsR1+NmfoS240cYbdsdEB3xC uSlLPpGPeJkobYbyTa59nEMq0vMJT0XgcRnFa38dYTVw0EN81dfwtUeOl6/FJ77Tjsfj mmSOxZPqdje/qgrkEFDOyIY/6Rm3wBe33fmsJPCSAlYxPkZfnEJ+aD7dNJeL7buAs3O4 3F9Q== X-Gm-Message-State: APjAAAUA45A7JAcK2Db+zvEaJMOpduKSc1uEL9i8MC36JKmhjvZ+NUQT ex036IN0xhm5gmTRsRED7fZ3XCGF0c9s7OXlHN4Fvg== X-Google-Smtp-Source: APXvYqy/Q6afJNy0LQS59WHI7nm9Bwf35qNhWpREy7ZDMujKAV2zVihgn6t5jcgc9jiyj3OLo8RPKLBodNfP9RkVLcM= X-Received: by 2002:a02:710f:: with SMTP id n15mr10706322jac.119.1560652807439; Sat, 15 Jun 2019 19:40:07 -0700 (PDT) X-Mailinglist: mandoc-discuss Reply-To: discuss@mandoc.bsd.lv MIME-Version: 1.0 References: <20190614084313.GA17405@www.stare.cz> <20190614085423.GC17405@www.stare.cz> <20190614122941.GB25099@athene.usta.de> <20190614142714.GA34987@www.stare.cz> <20190614145415.GE25099@athene.usta.de> In-Reply-To: <20190614145415.GE25099@athene.usta.de> From: Matthew Singletary Date: Sat, 15 Jun 2019 22:39:55 -0400 Message-ID: Subject: Re: Mandoc for oil To: discuss@mandoc.bsd.lv Content-Type: multipart/alternative; boundary="000000000000348c10058b67cc50" --000000000000348c10058b67cc50 Content-Type: text/plain; charset="UTF-8" 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 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 > > --000000000000348c10058b67cc50 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
All,
=C2=A0I've got a first attempt at = an updated man page for osh (the pull request is https://github.com/oilshell/oi= l/pull/337). Any feedback would be appreciated.
=C2=A0But whi= le 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?
=C2=A0For example, are there any recommended ways to = generate/keep up to date command line flags based upon source code, or is t= he convention to handle those by hand?

Thanks,
Matt
=C2=A0

On Fri, Jun 14, 2019 at 10:54 AM= Ingo Schwarze <sc= hwarze@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:
>>=C2=A0 - 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 (=3D 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:

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

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

Yours,
=C2=A0 Ingo
--
=C2=A0To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv
--000000000000348c10058b67cc50-- -- To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from scc-mailout-kit-01.scc.kit.edu (scc-mailout-kit-01.scc.kit.edu [129.13.231.81]) by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id 3d8e13a3 for ; Sun, 16 Jun 2019 12:08:12 -0500 (EST) Received: from asta-nat.asta.uni-karlsruhe.de ([172.22.63.82] helo=hekate.usta.de) by scc-mailout-kit-01.scc.kit.edu with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (envelope-from ) id 1hcYdW-0006Xs-6U; Sun, 16 Jun 2019 19:08:11 +0200 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.77) (envelope-from ) id 1hcYdV-0007eQ-2o; Sun, 16 Jun 2019 19:08:09 +0200 Received: from athene.usta.de ([172.24.96.10]) by donnerwolke.usta.de with esmtp (Exim 4.84_2) (envelope-from ) id 1hcYdV-0004vN-0Z; Sun, 16 Jun 2019 19:08:09 +0200 Received: from localhost (athene.usta.de [local]) by athene.usta.de (OpenSMTPD) with ESMTPA id e140fcaa; Sun, 16 Jun 2019 19:08:09 +0200 (CEST) Date: Sun, 16 Jun 2019 19:08:08 +0200 From: Ingo Schwarze To: Matthew Singletary Cc: discuss@mandoc.bsd.lv Subject: Re: Mandoc for oil Message-ID: <20190616170808.GD71520@athene.usta.de> References: <20190614084313.GA17405@www.stare.cz> <20190614085423.GC17405@www.stare.cz> <20190614122941.GB25099@athene.usta.de> <20190614142714.GA34987@www.stare.cz> <20190614145415.GE25099@athene.usta.de> X-Mailinglist: mandoc-discuss Reply-To: discuss@mandoc.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: User-Agent: Mutt/1.8.0 (2017-02-23) 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