Bug 13218

On Wed, Aug 18, 1999 at 10:44:13AM +0400, Alexey M. Zelkin wrote:
> 
> I see that Chris Costelo already works on this task. There lot's
> style and look corrections for FreeBSD manpages. I don't know why, but patch
> is again huge :-)) Probably manpages last time were reviewed long time ago ...

I'm not sure what the purpose of the following hunk is...

Index: share/man/man4/man4.i386/meteor.4
===================================================================
RCS file: /usr/local/CVSROOT/src/share/man/man4/man4.i386/meteor.4,v
retrieving revision 1.8
diff -c -r1.8 meteor.4
[...]
*** 71,77 ****
  behavior is to not deallocate pages.
  .Pp
  .Em options "METEOR_DEALLOC_ABOVE=xxx"
! deallocate all pages above the specified number.  The default action is
  to not deallocate above any pages.
  .Pp
  3) Make and install the kernel.
--- 69,75 ----
  behavior is to not deallocate pages.
  .Pp
  .Em options "METEOR_DEALLOC_ABOVE=xxx"
! deallocate all pages above the specified number. The default action is
  to not deallocate above any pages.
  .Pp
  3) Make and install the kernel.
***************

If the only change is to single-space after the period, I strongly
object.  It looks like you are trying to make the line fit some
minimum width.  If this is the case, I'd rather you simply started a
newline after the period.  The advantage to this is that it makes
future diffs smaller and more readable.  Having simpler diffs, more
specific, diffs is highly desirable since it makes the job of the
translators easier.

Also, starting each sentence on a newline allows the manpages to have
the correct number of spaces used after each period (except in certain
broken instances).

Speaking of translators...if this was done by script, you may want
to supply a copy of the script with this PR.  It might (or might
not) be useful.


Also, we don't have a program named bsd2dos.  Some of the .Xr's you've
added don't exist.  This doesn't bother me too much, but....


-- 
This is my .signature which gets appended to the end of my messages.

hi,

> I'm not sure what the purpose of the following hunk is...
> 
[hunk skiped]
> 
> If the only change is to single-space after the period, I strongly
> object.  It looks like you are trying to make the line fit some
> minimum width.  If this is the case, I'd rather you simply started a
> newline after the period.  The advantage to this is that it makes
> future diffs smaller and more readable.  Having simpler diffs, more
> specific, diffs is highly desirable since it makes the job of the
> translators easier.

Hmm... Looks like I just automaticly adjusted width to minimum. ;-( Anyway 
this hunk have no any special functionality, therefore you can ignore it.
 
> Speaking of translators...if this was done by script, you may want
> to supply a copy of the script with this PR.  It might (or might
> not) be useful.
I have TODO record to join lots of script which I'd used for detecting
these sorts of problems.

> Also, we don't have a program named bsd2dos.  Some of the .Xr's you've
> added don't exist.  This doesn't bother me too much, but....
Hey... Take a look again on this hunk. And you'll see that I'd 
replaced ".Xr bsd2dos 1" with reference to "unix2dos (from ports collection)"

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

hi,

> > Speaking of translators...if this was done by script, you may want
> > to supply a copy of the script with this PR.  It might (or might
> > not) be useful.
> I have TODO record to join lots of script which I'd used for detecting
> these sorts of problems.

Wonna say that I have a lot of sh(1) scripts, but planing to
convert it to perl, join and make something named "mdoclint".

Which checks I am proposing to include there (draft):

1. .Dt, .Dd, .Os will present.
2. .Dt argument will be uppercase.
3. All chunks "\([1-9]\)" will be converted to ".Xr"
4. All .Xr's will be reachable or replaced with .Pr or .Ur 
5. SEE ALSO .Xr's will be sorted.
6. Sort of checks for .Sh values, quotes etc.
7. Probably include functionality of checknr(1)

Comments and additions are welcome.

NOTE: I am not fast in perl because just started to learn this
language, and if you're interesting to participate -- contact me.

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

Comment 4 mpp 1999-08-18 23:03:00 UTC

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

I'll take care of getting these fixed. 

> >Synopsis:       Many manpages still not conformed mdoc(7) style
> 
> BTW, according sh(1). It has references to alias(1) and set(1). But real
> manpages for alias and set point to csh(1). Therefore I've replaced
> .Xr with .Sx (section reference) because sh(1) has there sections.
> Mike what do you think ?

.Sx should be used to refernce other sections that are declared
with .Sh, so this isn't right.  The text should probably just
be changed to say something like: "see the description of the 
alias command elsewhere in this document".

The shell-builtins are a documentation problem anyways.
"man alias" gives you the csh man page, but it isn't listed
in the "NAME" section so it won't appear in "whatis" output.  
"man set" gives you nothing.   This becomes more of a problem since 
both sh and csh have some of the same builtins.

The easiest thing might be to create a builtin(1) man page
that briefly describes both shells builtin commands,
and redirects the user to sh(1) and csh(1) for syntax and
further details.

-Mike
--
Mike Pritchard
mpp@FreeBSD.ORG or mpp@mpp.pro-ns.net

Comment 6 Alexey Zelkin 2000-11-22 18:00:57 UTC

State Changed
From-To: open->analyzed

Submited patch mostly commited, but some trickly things left 

Comment 7 Alexey Zelkin 2000-11-22 18:00:57 UTC

Responsible Changed
From-To: mpp->phantom

I'll fix left things

Comment 8 Alexey Zelkin 2001-05-29 15:12:48 UTC

State Changed
From-To: analyzed->closed

fixed while ago