cvs commit: src/share/examples/ses/getencstat getencstat.0 src/share/examples/ses/sesd sesd.0 src/share/examples/ses/setencstat setencstat.0 src/share/examples/ses/setobjstat setobjstat.0 src/shar

[Ruslan Ermilov]

On Thu, Feb 10, 2005 at 03:02:49PM +1100, Bruce Evans wrote:
> On Wed, 9 Feb 2005, Ceri Davies wrote:
> 
> > On Wed, Feb 09, 2005 at 06:07:17PM +0000, Ruslan Ermilov wrote:
> > > ru          2005-02-09 18:07:17 UTC
> > >
> > >   FreeBSD src repository
> > >
> > >   Modified files:
> > >   ...
> > >     share/man/man9       VOP_ACLCHECK.9 acl.9 microtime.9 mutex.9
> > >                          style.9 tvtohz.9 vfs_unmountall.9
>                              ^^^^^^^
> > >   Log:
> > >   Fixed the misplaced $FreeBSD$.
> >
> > style(9) doesn't say anything about this - could you add something
> > please?
> 
It actually does.  Manpages are similar to C header files in this
respect, i.e., the following apply, among other:

- after a copyright header, there's a blank line, and then $FreeBSD$;
- $FreeBSD$ should exist only once, except in the style.9 manpage;
- keep and do not edit foreign IDs.

> style.9 says a lot about this for C programs, and used to say something
> about this for man pages by example: $FreeBSD$ goes immediately after
> the vendor id.
> 
Except it actually says to put $FreeBSD$ after a copyright block, and
do not edit/move foreign IDs, so in case if the vendor ID was put
before copyright block, I kept it there, and just placed $FreeBSD$
where it belongs according to style(9) and template manpages
(/usr/share/examples/mdoc/).

> However, the example doesn't obviously apply to man
> pages because it is in a form suitable for C headers (a C comment),
> 
The C headers example in style(9) fits nicely with manpages.

> though it was intended to be a self-referential example for the man
> page itself.
> 
It's hard to guess, as manpages use different style of comments.

> The vendor id in it had to be misplaced to not set a bad
> example by moving the vendor id,
> 
You mean misplaced in the manpage's source?

> and the $FreeBSD$ in it had to be
> misplaced to not set a bad example by placing it elsewhere than after
> the vendor id.
> 
You mean misplaced in the manpage's source?

> Now there is another buggy example in the comment at the top of the
> man page.  The new bugs are not having the vendor id there, and
> incompleteness -- the example can only be seen by reading the source
> file.
> 
Well, the copyright is also not that of the vendor, either.  ;)

> style.9 is special since it has to give self-referential examples.  It
> needs at least 1 more $FreeBSD$ and 1 or 2 more vendor ids to obviously
> cover man pages:
> - a literal vendor id and $FreeBSD$ pair in the form of a man page comment
> 
I think this is not necessary.  Manpage example can be viewed by
viewing the style.9 source.  This is pretty self-referential.  ;)

> - maybe another vendor id before the $FreeBSD$ in the comment at the top
>   of the man page.  This is not quite right because style.9 isn't really
>   a man page and the vendor didn't put the id there.
> 
It should be as per style(9):

%%%
Index: style.9
===================================================================
RCS file: /home/ncvs/src/share/man/man9/style.9,v
retrieving revision 1.117
diff -u -p -r1.117 style.9
--- style.9	9 Feb 2005 18:07:17 -0000	1.117
+++ style.9	10 Feb 2005 08:30:19 -0000
@@ -23,9 +23,10 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
+.\"	From: @(#)style	1.14 (Berkeley) 4/28/95
 .\" $FreeBSD: src/share/man/man9/style.9,v 1.117 2005/02/09 18:07:17 ru Exp $
 .\"
-.Dd December 7, 2001
+.Dd February 10, 2005
 .Dt STYLE 9
 .Os
 .Sh NAME
%%%


Cheers,
-- 
Ruslan Ermilov
ru at FreeBSD.org
FreeBSD committer
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 187 bytes
Desc: not available
Url : http://lists.freebsd.org/pipermail/cvs-src/attachments/20050210/ed8af317/attachment.bin