Bug 13144

Comment 1 mpp 1999-08-14 23:13:12 UTC

Responsible Changed
From-To: freebsd-doc->mpp

I've already been working on some of these issues, and the 
attached patch helps me along a lot. 

> >Number:         13144
> >Category:       docs
> >Synopsis:       Many manual pages not conformed mdoc(7) style.
> 
> I am working on translation man pages to russian language and found
> a lot of style inconsistenses.
> 
> Patch is huge. More than 180 pages were updated.
> 
> What's changed ?
> 
> main points:
>   . -mdoc style fixes (according to mdoc(7))

99.9% of these  of these looked good.  I've got the 2 or 3 bad ones written
down.

>   . xrefs sorted

These all looked good on my first pass over this.
  
> additional points:
>   . Correcting Section Headers names (like AUTHOR -> AUTHORS). See mdoc(7) for
>     complete list correct headers.

Since there are so many of these man pages out there, I'm almost thinking
that we should add document that it is OK to use these.  However,
I did notice that some of the ones you updated had multiple authors
listed, so people are are forgetting to change AUTHOR to AUTHORS when
adding a second person to the author list.  But if we fix them all
now, and just keep an eye on all new man pages, it shouldn't
be a problem again in the future.

Then there are the man pages in contrib/.  I would leave the style
things alone in those man pages and request that the author fix
them.  That will make importing new versions of these easier.

>   . FreeBSD.ORG -> FreeBSD.org
>   . few references like "<portname>(1) (yet another port)" expanded to
>   "/usr/ports/<category>/<portname>". Maybe it's good idea to do it with all
>   same references, e.g. gated(1),portlint(1) ? It will make references more

.Xr <path reference>

is illegal, and is going to cause man page checking scripts to choke.
I've been toying with the idea of adding a ".Pr" macro (ports reference).
E.g.

.Pr gated 1

Would expand to something like:

gated(1) (from the portse collection)

I suppose we could also do:

.Pr gated 1 net

gated(1) (from the ports net collection)

>   clear and minimize "invlaid cross references" count.

These all looked good from my first pass over this.

-Mike

Comment 3 mpp 1999-08-15 12:00:35 UTC

State Changed
From-To: open->closed

99% of the supplied patch was applied, thanks a lot!!! 

I made some minor corrections while doing all of this. 
Some were related to the patch, some were just other things I noticied 
while reviewing the patch. 

I changed the xrefs that you changed to /usr/ports/<cat>/<port> 
back to ".Xr portname #", but I listed them with a header 
that said they are part of the ports collection.  These do need 
to be handled better, but until then, I think this is the best 
alternative. 

I didn't apply any of the patches to the src/contrib directory. 
These were all style fixes, and didn't change the resulting 
output.  These should be fixed by the original author, 
which should propogate to our sources sooner or later. 
Making FreeBSD specific style changes to contrib software 
just makes it harder to import new versions. 

Thanks for all of your work on this. 

Comment 4 mpp 1999-08-15 12:00:35 UTC

Responsible Changed
From-To: mpp->freebsd-doc

hi,

> > >Number:         13144

> > I am working on translation man pages to russian language and found
> > a lot of style inconsistenses.
> > 
> > Patch is huge. More than 180 pages were updated.
> > 
> > What's changed ?
> > 
> > main points:
> >   . -mdoc style fixes (according to mdoc(7))
> 
> 99.9% of these  of these looked good.  I've got the 2 or 3 bad ones written
> down.

Which ones exactly ?

> > additional points:
> >   . Correcting Section Headers names (like AUTHOR -> AUTHORS). See mdoc(7) for
> >     complete list correct headers.
> 
> Since there are so many of these man pages out there, I'm almost thinking
> that we should add document that it is OK to use these.  However,
> I did notice that some of the ones you updated had multiple authors
> listed, so people are are forgetting to change AUTHOR to AUTHORS when
> adding a second person to the author list.  But if we fix them all
> now, and just keep an eye on all new man pages, it shouldn't
> be a problem again in the future.

hmm ... maybe I'll improve my script which checked these inconsistenses and
submit it (something like portlint). Then we just can add note to mdoc(7)
as requrement to check new/updated manpages with that ? And maybe once per
month check all manpages in source tree ? I don't think that adding new, but
with same meaning section headers names to style guide is good way.

> Then there are the man pages in contrib/.  I would leave the style
> things alone in those man pages and request that the author fix
> them.  That will make importing new versions of these easier.

Ok, I will send them to bind(8) mainteiner.
 
> >   . few references like "<portname>(1) (yet another port)" expanded to
> >   "/usr/ports/<category>/<portname>". Maybe it's good idea to do it with all
> >   same references, e.g. gated(1),portlint(1) ? It will make references more
> I've been toying with the idea of adding a ".Pr" macro (ports reference).
>
> E.g.
> 
> .Pr gated 1
> 
> Would expand to something like:
> 
> gated(1) (from the portse collection)

It's really that I asked for!

> I suppose we could also do:

> .Pr gated 1 net
Sure.

> gated(1) (from the ports net collection)

-- 
Sincerely Yours,   | phantom@crimea.edu      (primary)
Alexey Zelkin      | phantom@scorpion.crimea.ua (home)
                   | ICQ: #6196584,  FIDO: 2:460/12.26