Hi,

Mike Belopuhov wrote on Sun, Sep 18, 2016 at 01:35:45PM +0200:
> On Sun, Sep 18, 2016 at 06:15 +0000, Visa Hankala wrote:
>> On Sat, Sep 17, 2016 at 02:40:09PM +0100, Rafael Neves wrote:

>>> Here follows a manpage for octuctl(4), based on dwctwo(4) manpage.
>>> I am not sure if the title should stop in Controller or in Interface,
>>> so I mantained the phrasing of commit.

I don't know either, so i left your wording untouched.

>> My name does not belong to the copyright because I am not the author
>> of this work.
>> Is it customary to write manual pages for driver glue?

> Traditionally, you'd add a line "echi* at octuctl?" to echi(4)
> man page with a cross reference to octuctl(4) in the SEE ALSO
> section

Given that that isn't done for obio(4) on landisk and socppc either,
that octuctl(4/octeon) is MD, and that .Xrs from MI to MD pages
are slightly awkward, i'd maybe not put anything into ehci(4).
Correct me if you think that's wrong, i know little about drivers.

> and then add the description of what is octuctl into
> it's own man page.
> 
> Just like usb(4) mentions dwctwo? attachment and then dwctwo(4)
> describes what is it.

So, here is a cleaned-up version:

 - Move the new page to the proper directory.
 - Mention it in the Makefile.
 - Put the correct manual page author into the Copyright notice.
 - Add the architecture to the .Dt line.
 - Remove the needless .Pq from the .Cd line
   (it might be useful in ehci(4), but not here).
 - Remove the argument from .Nm in the DESCRIPTION.
 - Append an AUTHORS section.

In long and complicated manuals, the AUTHORS section can also contain
a sentence like:  This manual page was written by Rafael Neves.
But i don't think that's interesting for such a short manual.

OK?
  Ingo


Index: Makefile
===================================================================
RCS file: /cvs/src/share/man/man4/man4.octeon/Makefile,v
retrieving revision 1.4
diff -u -p -r1.4 Makefile
--- Makefile    17 Nov 2015 13:25:36 -0000      1.4
+++ Makefile    18 Sep 2016 13:16:14 -0000
@@ -1,6 +1,6 @@
 #      $OpenBSD: Makefile,v 1.4 2015/11/17 13:25:36 visa Exp $
 
-MAN=   amdcf.4 cnmac.4 octrng.4 octrtc.4
+MAN=   amdcf.4 cnmac.4 octrng.4 octrtc.4 octuctl.4
 MANSUBDIR=octeon
 
 .include <bsd.prog.mk>
Index: octuctl.4
===================================================================
RCS file: octuctl.4
diff -N octuctl.4
--- /dev/null   1 Jan 1970 00:00:00 -0000
+++ octuctl.4   18 Sep 2016 13:16:14 -0000
@@ -0,0 +1,48 @@
+.\"    $OpenBSD$
+.\"
+.\" Copyright (c) 2016 Rafael Neves <raf...@diksless.io>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate$
+.Dt OCTUCTL 4 octeon
+.Os
+.Sh NAME
+.Nm octuctl
+.Nd Octeon II USB Controller Interface
+.Sh SYNOPSIS
+.Cd "octuctl0 at iobus? irq 56"
+.Cd "ehci0    at octuctl?"
+.Cd "ohci0    at octuctl?"
+.Sh DESCRIPTION
+The
+.Nm
+driver provides support for the Octeon II USB Controller Interface,
+which provides an interface to
+.Xr ehci 4
+and
+.Xr ohci 4
+devices.
+.Sh SEE ALSO
+.Xr ehci 4 ,
+.Xr ohci 4
+.Sh HISTORY
+The
+.Nm
+driver first appeared in
+.Ox 6.0 .
+.Sh AUTHORS
+The
+.Nm
+driver was written by
+.An Jonathan Matthew Aq Mt jmatt...@openbsd.org .

Reply via email to