Re: correct includes in man(2) pages
On Wed, Jun 05, 2013 at 06:36:11PM +0200, Jan Klemkow wrote: The only special case is this one: Index: libc/sys/quotactl.2 === RCS file: /cvs/src/lib/libc/sys/quotactl.2,v retrieving revision 1.11 diff -u -p -r1.11 quotactl.2 --- libc/sys/quotactl.2 31 May 2007 19:19:33 - 1.11 +++ libc/sys/quotactl.2 5 Jun 2013 16:25:27 - @@ -40,8 +40,8 @@ .Nm quotactl .Nd manipulate filesystem quotas .Sh SYNOPSIS -.Fd #include ufs/ufs/quota.h /* for ufs quotas */ -.Fd #include unistd.h +.In ufs/ufs/quota.h /* for ufs quotas */ +.In unistd.h .Ft int .Fn quotactl const char *path int cmd int id char *addr .Sh DESCRIPTION I had to replace the tab between 'quota.h' and the comment with a normal space. mandoc(1) do not render it properly with a tabulator. we should be careful here. mandoc renders it like this: SYNOPSIS #include ufs/ufs/quota.h /* for ufs quotas */ #include unistd.h whereas groff does this: SYNOPSIS #include ufs/ufs/quota.h /* for ufs quotas */ #include unistd.h our mdoc(7) states that .In should have exactly one argument. i don;t think groff says the same, but it does document (groff_mdoc(7)) that .In causes a newline after its argument. we should probably not have more than one argument in our pages for the .In lines, and, arguably, mandoc should behave the same as groff. ingo? jmc
Re: correct includes in man(2) pages
On Wed, Jun 05, 2013 at 17:56, Jason McIntyre wrote: we should be careful here. mandoc renders it like this: SYNOPSIS #include ufs/ufs/quota.h /* for ufs quotas */ #include unistd.h whereas groff does this: SYNOPSIS #include ufs/ufs/quota.h /* for ufs quotas */ #include unistd.h our mdoc(7) states that .In should have exactly one argument. i don;t think groff says the same, but it does document (groff_mdoc(7)) that .In causes a newline after its argument. I think we should delete the comment. It should not be surprising that a function manipulating quotas needs to include the quota header.
Re: correct includes in man(2) pages
On Wed, Jun 05, 2013 at 01:14:15PM -0400, Ted Unangst wrote: On Wed, Jun 05, 2013 at 17:56, Jason McIntyre wrote: we should be careful here. mandoc renders it like this: SYNOPSIS #include ufs/ufs/quota.h /* for ufs quotas */ #include unistd.h whereas groff does this: SYNOPSIS #include ufs/ufs/quota.h /* for ufs quotas */ #include unistd.h our mdoc(7) states that .In should have exactly one argument. i don;t think groff says the same, but it does document (groff_mdoc(7)) that .In causes a newline after its argument. I think we should delete the comment. It should not be surprising that a function manipulating quotas needs to include the quota header. that's fine. but i think there are other man pages that do this. so fixing one page is not a solution. (might be wrong though - haven;t checked) jmc
Re: correct includes in man(2) pages
we should probably not have more than one argument in our pages for the .In lines, and, arguably, mandoc should behave the same as groff. Regardless, the comment doesn't add much. #include ufs/ufs/quota.h is pretty self-explanatory that it's for UFS quotas. :)
