Re: Manpage for uctuctl(4)

[Ingo Schwarze]

Hi Rafael,

Rafael Neves wrote on Sun, Sep 18, 2016 at 04:48:37PM +0100:

> I have to admit that the idea of derived work in such short
> content manpage is very ethereal for me. :)

I think you are not alone.  If i understand correctly, disputes
over Copyright of small amounts of content end up in court more
easily than disputes about large amounts of content, both regarding
works that are very small in the first place (because users tend
to argue they are so trivial they don't deserve Copyright protection
at all) and regarding very small extracts from larger works (because
brevity of an extract is one of the criteria that helps to argue
for fair use).

Anyway, i have committed an initial version of the manual.
In case it still needs tweaking, that can be done in the tree.

Yours,
  Ingo

Re: Manpage for uctuctl(4)

[Ingo Schwarze]

Hi Rafael,

Rafael Neves wrote on Sun, Sep 18, 2016 at 12:29:35PM +0100:
> On Sun, Sep 18, 2016 at 03:33:00PM +0200, Ingo Schwarze wrote:

>>  - Put the correct manual page author into the Copyright notice.

> I think that I shouldn't be in the copyright notice, because thre
> is no original work from me. I just copied the dwctwo(4) manpage
> and tweaked it, it is why there is Visa name there.

Technically, what you sent is a *derived work*.  In that case,
the original Copyright applies to the unchanged parts, and new
Copyright comes into existence covering your changes, so in
general, there should be two Copyright lines with different names.

However, diffing the two files, i find that all that remains from
the original file is this:

 .Os
 .Sh NAME
 .Sh SYNOPSIS
 .Sh DESCRIPTION
 The
 .Nm
 driver provides support for ...
 devices.
 .Sh SEE ALSO
 .Xr ehci 4 ,
 .Xr ohci 4
 .Sh HISTORY
 The
 .Nm
 driver first appeared in

That is all boilerplate text, imho insufficient to establish
Copyright, and besides, Visa explicitly confirmed that he does not
recognize the file as containing any of his work any longer, after
your changes.  If you delete all original work from a file, you can
delete the Copyright notice as well.  On the other hand, adding
your Copyright makes sense because you changed and added various
lines of text containing actual content.  So if the file is worthy
of Copyright at all - which i think it is, creativity standards in
Copyright are quite low - your name should be there.  And even if
the file as whole would not meet the creativity threshold, putting
your Copyright header is better than having none because it avoids
doubt.

Do you still object?

> I think it is like when you copy a source file and tweaks some
> magic numbers, or use a whole file in some other place in the tree
> with some modifications. It generally does not implies putting the
> name in the copyright notice, what I think is correct.

For minor changes in a substantial file, you are right.  But in
this case, non-boilerplate Copyrightable content is sparse in the
first place, and you changed most of what there is.

Yours,
  Ingo

Re: Manpage for uctuctl(4)

[Visa Hankala]

On Sun, Sep 18, 2016 at 03:33:00PM +0200, Ingo Schwarze wrote:
> 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

ok visa@

Re: Manpage for uctuctl(4)

[Rafael Neves]

Hi,

On Sun, Sep 18, 2016 at 03:33:00PM +0200, Ingo Schwarze wrote:
> Hi,
> 
> Mike Belopuhov wrote on Sun, Sep 18, 2016 at 01:35:45PM +0200:
> > On Sun, Sep 18, 2016 at 06:15 +, 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.
Agreed.
>  - Mention it in the Makefile.
Agreed.
>  - Put the correct manual page author into the Copyright notice.
I think that I shouldn't be in the copyright notice, because thre is no 
original work from me. I just copied the dwctwo(4) manpage and tweaked it, it 
is why there is Visa name there.

I think it is like when you copy a source file and tweaks some magic numbers, 
or use a whole file in some other place in the tree with some modifications. It 
generally does not implies putting the name in the copyright notice, what I 
think is correct.

>  - Add the architecture to the .Dt line.
Agreed.
>  - Remove the needless .Pq from the .Cd line
>(it might be useful in ehci(4), but not here).
Agreed, thanks!
>  - Remove the argument from .Nm in the DESCRIPTION.
Agreed, thanks!
>  - Append an AUTHORS section.
Agreed.
> 
> 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.
Agreed. And in this specific case, I have just tweaked an existing manpage.
> 
> OK?
>   Ingo
>
[snip] 

Re: Manpage for uctuctl(4)

[Ingo Schwarze]

Hi,

Mike Belopuhov wrote on Sun, Sep 18, 2016 at 01:35:45PM +0200:
> On Sun, Sep 18, 2016 at 06:15 +, 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
--- Makefile17 Nov 2015 13:25:36 -  1.4
+++ Makefile18 Sep 2016 13:16:14 -
@@ -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 
Index: octuctl.4
===
RCS file: octuctl.4
diff -N octuctl.4
--- /dev/null   1 Jan 1970 00:00:00 -
+++ octuctl.4   18 Sep 2016 13:16:14 -
@@ -0,0 +1,48 @@
+.\"$OpenBSD$
+.\"
+.\" Copyright (c) 2016 Rafael Neves 
+.\"
+.\" 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 "ehci0at octuctl?"
+.Cd "ohci0at 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 .

Re: Manpage for uctuctl(4)

[Mike Belopuhov]

On Sun, Sep 18, 2016 at 06:15 +, Visa Hankala wrote:
> On Sat, Sep 17, 2016 at 02:40:09PM +0100, Rafael Neves wrote:
> > Hi, 
> > 
> > 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.
> > 
> > Index: share/man/man4/octuctl.4
> > ===
> > RCS file: share/man/man4/octuctl.4
> > diff -N share/man/man4/octuctl.4
> > --- /dev/null   1 Jan 1970 00:00:00 -
> > +++ share/man/man4/octuctl.47 Sep 2016 21:55:30 -
> > @@ -0,0 +1,43 @@
> > +.\"$OpenBSD: octuctl.4,v 1.3 2016/02/02 17:38:20 jmc Exp $
> > +.\"
> > +.\" Copyright (c) 2016 Visa Hankala
> > +.\"
> > +.\" 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: July 28 2016 $
> > +.Dt OCTUCTL 4
> > +.Os
> > +.Sh NAME
> > +.Nm octuctl
> > +.Nd Octeon II USB Controller Interface
> > +.Sh SYNOPSIS
> > +.Cd "octuctl0 at iobus? irq 56" Pq "octeon"
> > +.Cd "ehci0at octuctl?"
> > +.Cd "ohci0at octuctl?"
> > +.Sh DESCRIPTION
> > +The
> > +.Nm octuctl
> > +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 .
> 
> 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 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.

Manpage for uctuctl(4)

[Rafael Neves]

Hi, 

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.

Index: share/man/man4/octuctl.4
===
RCS file: share/man/man4/octuctl.4
diff -N share/man/man4/octuctl.4
--- /dev/null   1 Jan 1970 00:00:00 -
+++ share/man/man4/octuctl.47 Sep 2016 21:55:30 -
@@ -0,0 +1,43 @@
+.\"$OpenBSD: octuctl.4,v 1.3 2016/02/02 17:38:20 jmc Exp $
+.\"
+.\" Copyright (c) 2016 Visa Hankala
+.\"
+.\" 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: July 28 2016 $
+.Dt OCTUCTL 4
+.Os
+.Sh NAME
+.Nm octuctl
+.Nd Octeon II USB Controller Interface
+.Sh SYNOPSIS
+.Cd "octuctl0 at iobus? irq 56" Pq "octeon"
+.Cd "ehci0at octuctl?"
+.Cd "ohci0at octuctl?"
+.Sh DESCRIPTION
+The
+.Nm octuctl
+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 .