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

[Bruce Evans]

On Thu, 10 Feb 2005, Ruslan Ermilov wrote:

> On Thu, Feb 10, 2005 at 03:02:49PM +1100, Bruce Evans wrote:
> > On Wed, 9 Feb 2005, Ceri Davies wrote:
> > > 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$;

It literally says "rcsid" instead of "$FreeBSD$" here, and only mentions
$FreeBSD$ by example.  I avoid using "rcsid" since ids may or may not be
rcsids.

> - $FreeBSD$ should exist only once, except in the style.9 manpage;

It actually says "Version control system ID tags" instead of "$FreeBSD$"
here.  This covers $FreeBSD$ with more than an example, but without the
example it only requires at most 1 $FreeBSD$ and not exactly 1.

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

Except is actually says that there is an rcsid after the copyright block,
and then gives an example with an sccsid instead of an rcsid.  Only the
example shows that other ids follow the "rcsid".

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

That is OK with me, except in style(9) it makes the self references harder
to untangle.

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

To avoid guesses, it should be formatted like a man page comment if
it applies to man pages.  style.9 also has problems describing both
a C program and a header in the same file.

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

Sort of.

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

Sort of.  Neither of these ids is needed in the output except for their
possibly unintentional side effect of sort of documenting $FreeBSD$ for
headers and man pages.

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

All section 9 man pages can better be viewed by viewing their source,
(*.c, not *.9) ;-).

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

OK.  I have a rule for "From:" too: use it iff the file was renamed,
including for repo-copying.

>  .\"
> -.Dd December 7, 2001
> +.Dd February 10, 2005

Apperently the mdoc police were asleep :-).

>  .Dt STYLE 9
>  .Os
>  .Sh NAME
> %%%

Bruce