policy for updating mdoc .Dd ?

classic Classic list List threaded Threaded
9 messages Options
Reply | Threaded
Open this post in threaded view
|

policy for updating mdoc .Dd ?

Jeremy C. Reed
What is the policy for updating mdoc .Dd ?

According to mdoc(7) it is the "Document date". I find it useful to see
how old or new the man page is (especially since the .Os value is based on
the system's mdoc.local).

 Jeremy C. Reed

Reply | Threaded
Open this post in threaded view
|

Re: policy for updating mdoc .Dd ?

Theo de Raadt
> According to mdoc(7) it is the "Document date". I find it useful to see
> how old or new the man page is (especially since the .Os value is based on
> the system's mdoc.local).

I believe it should be updated when a change in functionality is made.
ie. the same policy we have for other interfaces in the system.

Reply | Threaded
Open this post in threaded view
|

Re: policy for updating mdoc .Dd ?

Jason McIntyre-2
On Fri, Mar 24, 2006 at 06:01:50PM -0700, Theo de Raadt wrote:
> > According to mdoc(7) it is the "Document date". I find it useful to see
> > how old or new the man page is (especially since the .Os value is based on
> > the system's mdoc.local).
>
> I believe it should be updated when a change in functionality is made.
> ie. the same policy we have for other interfaces in the system.

personally i think it should be made every time a change is made to a
page, no matter how minor. but until we come up with a way of making it
happen automatically, at commit time, i think it's unworkable.

(to the original poster): cvs is the most reliable way to get that info

jmc

Reply | Threaded
Open this post in threaded view
|

Re: policy for updating mdoc .Dd ?

Alexander Yurchenko
On Sat, Mar 25, 2006 at 08:18:13AM +0000, Jason McIntyre wrote:

> On Fri, Mar 24, 2006 at 06:01:50PM -0700, Theo de Raadt wrote:
> > > According to mdoc(7) it is the "Document date". I find it useful to see
> > > how old or new the man page is (especially since the .Os value is based on
> > > the system's mdoc.local).
> >
> > I believe it should be updated when a change in functionality is made.
> > ie. the same policy we have for other interfaces in the system.
>
> personally i think it should be made every time a change is made to a
> page, no matter how minor. but until we come up with a way of making it
> happen automatically, at commit time, i think it's unworkable.

but you'll have dozens of free commits like ``bump date for previous''! ;-)

>
> (to the original poster): cvs is the most reliable way to get that info
>
> jmc

--
   Alexander Yurchenko

Reply | Threaded
Open this post in threaded view
|

Re: policy for updating mdoc .Dd ?

Jason McIntyre-2
On Sat, Mar 25, 2006 at 11:56:31AM +0300, Alexander Yurchenko wrote:
> >
> > personally i think it should be made every time a change is made to a
> > page, no matter how minor. but until we come up with a way of making it
> > happen automatically, at commit time, i think it's unworkable.
>
> but you'll have dozens of free commits like ``bump date for previous''! ;-)
>

yes, that's exactly why i don't want it...
jmc

Reply | Threaded
Open this post in threaded view
|

Re: policy for updating mdoc .Dd ?

Thorsten Glaser-3
In reply to this post by Alexander Yurchenko
Alexander Yurchenko dixit:

>> personally i think it should be made every time a change is made to a
>> page, no matter how minor. but until we come up with a way of making it
>> happen automatically, at commit time, i think it's unworkable.
>
>but you'll have dozens of free commits like ``bump date for previous''! ;-)

Uh, no. When someone changes the manual page, he can adjust
the .Dd in the same page within the same commit.

//mirabile
--
I believe no one can invent an algorithm. One just happens to hit upon it
when God enlightens him. Or only God invents algorithms, we merely copy them.
If you don't believe in God, just consider God as Nature if you won't deny
existence. -- Coywolf Qi Hunt

Reply | Threaded
Open this post in threaded view
|

Re: policy for updating mdoc .Dd ?

Jason McIntyre-2
On Sat, Mar 25, 2006 at 01:16:27PM +0000, Thorsten Glaser wrote:

> Alexander Yurchenko dixit:
>
> >> personally i think it should be made every time a change is made to a
> >> page, no matter how minor. but until we come up with a way of making it
> >> happen automatically, at commit time, i think it's unworkable.
> >
> >but you'll have dozens of free commits like ``bump date for previous''! ;-)
>
> Uh, no. When someone changes the manual page, he can adjust
> the .Dd in the same page within the same commit.
>

right. but who will remember? at the end of the day, someone will need
to run around date bumping...just like grange was talking about.

jmc

Reply | Threaded
Open this post in threaded view
|

Re: policy for updating mdoc .Dd ?

Jeremy C. Reed
On Sat, 25 Mar 2006, Jason McIntyre wrote:

> > Uh, no. When someone changes the manual page, he can adjust
> > the .Dd in the same page within the same commit.

Exactly. That is why I asked what the policy was. (I was not suggesting
doing it later, but for later updates it would be useful. In my own
experience, in other projects, developers have reminded me to update .Dd a
few times though :)

> right. but who will remember? at the end of the day, someone will need
> to run around date bumping...just like grange was talking about.

On Sat, 25 Mar 2006, Jason McIntyre wrote:
> (to the original poster): cvs is the most reliable way to get that info

Or ident if you have the file. But man pages may be made available via
webpages, in print, etc.

I was just curious about this, because Theo pointed to the signal manpage
on the web yesterday and the manual was dated almost twelve years old.


 Jeremy C. Reed

echo ':6DB6=88>?;@69876tA=AC8BB5tA6487><' | tr '4-F' 'wu rofIn.lkigemca'

Reply | Threaded
Open this post in threaded view
|

Re: policy for updating mdoc .Dd ?

Otto Moerbeek
In reply to this post by Jason McIntyre-2
On Sat, 25 Mar 2006, Jason McIntyre wrote:

> On Sat, Mar 25, 2006 at 01:16:27PM +0000, Thorsten Glaser wrote:
> > Alexander Yurchenko dixit:
> >
> > >> personally i think it should be made every time a change is made to a
> > >> page, no matter how minor. but until we come up with a way of making it
> > >> happen automatically, at commit time, i think it's unworkable.
> > >
> > >but you'll have dozens of free commits like ``bump date for previous''! ;-)
> >
> > Uh, no. When someone changes the manual page, he can adjust
> > the .Dd in the same page within the same commit.
> >
>
> right. but who will remember? at the end of the day, someone will need
> to run around date bumping...just like grange was talking about.

Just check netbsd src changes for a fine demonstration of that,


        -Otto