Menu

#345 man: Add possibility to suppress copyright/license output

output: manpages
closed-fixed
XSL (399)
3
2014-08-17
2006-04-10
No

Hello,

There is a minor bug, so a line-break is missing before
the '.SH "COPYRIGHT"'. The example I sent you a few
days ago can be used to reproduce that bug. The
resulting manpage source then looks like this:

.SH "AUTHOR"
author_first author_last <first.last@mail.tld>.SH
"COPYRIGHT"
Copyright \(co 2006 author_first author_last

A further wish: I saw the implementation of a COPYRIGHT
section. But for me, the copyright and/or legalnotice
informations are better put as comments into the
manpage header (where also Date, Generator, Author, ...
can be found). So it then looks like this:

.\" Title: ...
.\" Author: ...
.\" Generator: ...
.\" Date: ...
.\" Manual: ...
.\" Source: ...
.\" Copyright: ...
.\" License: ...
.\" ...

Could you implement such an option, so real sections
for both (currently only Copyright seems to be
supported) can be suppressed?

Regards, Daniel

Discussion

  • Michael(tm) Smith

    Logged In: YES
    user_id=118135

    > There is a minor bug, so a line-break is missing before
    > the '.SH "COPYRIGHT"'. The example I sent you a few
    > days ago can be used to reproduce that bug. The
    > resulting manpage source then looks like this:
    >
    > .SH "AUTHOR"
    > author_first author_last <first.last@mail.tld>.SH
    > "COPYRIGHT"
    > Copyright \(co 2006 author_first author_last

    Actually, when I process your source, I get this:

    .SH "AUTHOR"
    .PP
    \fBauthor_first\fR \fBauthor_last\fR <first.last@mail.tld>
    .sp -1n
    .IP
    Author.
    .SH "COPYRIGHT"

    That is, I get an indented paragraph with "Author."
    after the line with the author name and e-mail
    address and before the .SH "COPYRIGHT" line.

    I'm guessing you must be using a customization that
    suppresses that "Author." part?

     
  • Michael(tm) Smith

    Logged In: YES
    user_id=118135

    > But for me, the copyright and/or legalnotice
    > informations are better put as comments into the
    > manpage header (where also Date, Generator, Author, ...
    > can be found).

    Why?

    > Could you implement such an option, so real sections
    > for both (currently only Copyright seems to be
    > supported)

    Actually, output of Legalnotice is also supported. At
    least it works for me with the latest snapshot and with
    your "example_header" test document.

    > can be suppressed?

    Please help me understand exactly what use-case you have
    in mind for suppressing them in output but having them
    hidden in the roff comments.

    The sole purpose of putting a copyright notice in a
    document is to inform any potential users that the
    document is protected by copyright. Most users do not
    know or care where the roff source for a man page is
    and will not think to go looking for it in order to
    check for a copyright statement in it. So not having
    a copyright statement in the rendered output of your
    man page is effectively the same as not having a
    copyright statement at all. If you have the copyright
    statement only as a comment in your roff source,
    you could not claim that you gave adequate notice
    to users that the source was copyrighted, and what
    the name of the holder of the copyright holder is.

    And same goes for Legalnotice, when the text of the
    legalnotice is an explanation of the terms under
    which the material in your man page can be copied,
    modified, or redistributed. If you do not have the
    legalnotice contents in your rendered output, most
    users are never going to see them or know where to
    look for them.

    To me, if you don't want to have the copyright or
    legalnotice show up in your output, then do not include
    them in your DocBook source.

     
  • Michael(tm) Smith

    • assigned_to: nobody --> xmldoc
    • status: open --> pending
     
  • Daniel Leidert

    Daniel Leidert - 2006-04-10

    Logged In: YES
    user_id=1102637

    First: You are right. There is not a ug. I was using a
    customization, which will be dropped soon.

    Second:

    > Why?

    I don't want to make large extension to the stuff to read in
    a small manpage. Most manpages do not reproduce the
    copyright and/or legalnotice informations.

    > Actually, output of Legalnotice is also supported.

    I'm sorry. It seems, that a small modification suppressed
    that output. After using the real stylesheet, it works.

    > Please help me understand exactly what use-case you have
    > in mind for suppressing them in output but having them
    > hidden in the roff comments.

    I will try my best.

    > The sole purpose of putting a copyright notice in a
    > document is to inform any potential users that the
    > document is protected by copyright.

    That is true. But every work is protected by a copyright
    except the copyright owner gives other informations. So it's
    not always necessary to show this copyright there.

    > Most users do not
    > know or care where the roff source for a man page is
    > and will not think to go looking for it in order to
    > check for a copyright statement in it.

    That is also true. But many manpages have put the copyright
    notice, the disclaimers and/or license texts into the header
    as comments (e.g. the manpages describing the glibc
    functions, have a look at
    ftp://ftp.win.tue.nl/pub/linux-local/manpages/). To describe
    the situation at one example: The 3-clause BSD license does
    not say, that the binary/compiled/other forms must reproduce
    the copyright notice, ... in every case. Instead
    distribution of these informations can be done in other
    ways. So I don't need this information written inside the
    manpage. But I would still like to provide it. So a comment
    is really the best for me. But what you've said, is still true.

    > To me, if you don't want to have the copyright or
    > legalnotice show up in your output, then do not include
    > them in your DocBook source.

    This is of course a possible way. These informations can
    also be put as comments into the source. But because,
    putting it as comments into the roff source too is also
    common way, I would like to provide these informations in
    the roff source, without to have separate sections for them.
    On the other hand: I would like to have this info for
    HTML-formatted manpages. So removing the related elements
    would make it impossible to create the wanted output.

    I would appreciate to be able to choose, if the copyright
    notice, ... can be outputted to the manpage or only as a
    comment.

    Regards, Daniel

     
  • Daniel Leidert

    Daniel Leidert - 2006-04-10
    • status: pending --> open
     
  • Michael(tm) Smith

    • priority: 5 --> 3
    • labels: 321159 --> XSL
    • milestone: 541245 --> output: manpages
     
  • Michael(tm) Smith

    Logged In: YES
    user_id=118135

    I will try to implement support for this when I can.
    But I cannot get it done for the 1.70.0 release.

    Anyway, I don't really understand why you want to have
    the copyright appear in your HTML output but not in
    your man-page output. You may not think you need
    copyright info in your man pages, but your users might
    think differently. Consider tht case of a user who
    wants to copy and republish some portion of your man
    page. They will want to know who holds the copyright
    on it, and what the license terms are. Most will not
    think or want to have to go looking for it by finding
    and opening the source for your man page in a text
    editor or whatever.

    And a far as the glibc man pages and how they handle
    copyright, well, I can point you to many other man pages
    that have a copyright and license information in the
    actual man pages. Most of the man pages for GNU commands
    (sort, uniq, cat, etc.), for example.

     
  • Michael(tm) Smith

    • summary: man: Copyright section bug and wish for a comment-option --> man: Copyright as comment
     
  • Michael(tm) Smith

    Logged In: YES
    user_id=118135

     
  • Daniel Leidert

    Daniel Leidert - 2006-04-13

    Logged In: YES
    user_id=1102637

    Ok. Maybe HTML was a bad example. But e.g. pdf/ps and roff
    are better. pdf and ps source is not human readable. roff
    source is. So maybe the copyright and the license should
    appear on pdf/ps, but not directly in roff output.

    And I agree: Yes, there are many manpages, which output the
    copyright and license informations in the manpage. I only
    wanted to show, that there are also many examples, which
    have this information in the roff source. So both
    possibilities are commonly used. And even the Linux Man Page
    Howto does not tell anything about a COPYRIGHT or LICENSE
    section.

    For me using an own section for copyright and license would
    mean to output a large section (3-clause BSD-styled
    license), which can be larger than the rest of the document
    (I have some small manpages, which just describe a command,
    which does not have any options). I just want to avoid this,
    so the manpage is better readable for the end-user. I cannot
    disprove any of your arguments. I just want to show you my
    point of view.

    PS:
    > You may not think you need copyright info in your man
    > pages, but your users might think differently.

    I know a lot of people, which do not agree, that a copyright
    is always necessary, because the author automatically claims
    a copyright. But this discussion would go beyond the scope
    of this feature discussion :)

    Thanks for all of your work in docbook-xsl. The changes for
    1.70.0 already made my life easier.

    Regards, Daniel

     
  • Daniel Leidert

    Daniel Leidert - 2007-06-19
    • summary: man: Copyright as comment --> man: Add possibility to suppress copyright/license output
     
  • Daniel Leidert

    Daniel Leidert - 2007-06-19

    Logged In: YES
    user_id=1102637
    Originator: YES

    After our last discussion, I would like to change this request to the following: Drop my idea of adding the copyright and license information as comments to the groff source.

    Instead I would like to request the possibility to simply suppress the output of a copyright and license section. Your opinion?

     
  • Michael(tm) Smith

    Logged In: YES
    user_id=118135
    Originator: NO

    Daniel,

    My opinion is that if someone doesn't want a copyright and license statement in their document output, the can achieve that by not putting a copyright and license statement in their source.

    Are others asking for this (ability to suppress copyright in manpages output)? I mean, did somebody submit a Debian bug report or feature request related to this?

    Regardless, what problem is this change meant to solve? Are there cases where someone would want to have a copyright and license statement for a document appear in HTML and PDF output but not in man output? If so, why?

    I would think that you being involved with Debian, you can well understand the value in making copyright and license information easily available to end users at point of use -- at this case, in the body of a man page, so users of that page can know who holds the copyright on it and under what terms (if any) the text of that man page can be reused and republished.

    Not all users are sophisticated users (not even all Debian users) and not all would consider going to look for copyright info in/usr/share/doc nor in the (compressed) source for the man page. And even if they did, having the information there only is just making things harder for them -- making them do the work to hunt down the copyright info.

    And given that Debian packages form the foundations for other distributions -- most notably, Ubuntu -- for users far less savvy/sophisticated/techy that Debian users, and perhaps you can see that we're left with a big pool of users who are never going to see that copyright info if you suppress it and put it elsewhere instead.

    Anyway, I am very reluctant to add any feature that makes it easy for authors to hide source copyright information from end users, particularly if that copyright info is available in HTML and PDF output from the same source. But again, if you can explain what problem this would solve -- what the use case is here -- it would help me a lot.

    --Mike

     
  • Daniel Leidert

    Daniel Leidert - 2007-07-21

    Logged In: YES
    user_id=1102637
    Originator: YES

    I probably wasn't verboose enough about the intention. The possibility to suppress the output of the automatically prepared sections for Copyright/License and Authors should allow for writing own sections without dropping <authorgroup> or <copyright> or <legalnotice> in the source. So users are free to choose, if automatically prepared section will be created (default) or if they write their own sections. IMHO the solution is very easy by implementing one or two parameters e.g.

    man.suppress.copyright
    man.suppress.authors

    or similar to prevent docbook-xsl from automatically creating the related sections and give users the possibility to write own sections.

     
  • Michael(tm) Smith

    Logged In: YES
    user_id=118135
    Originator: NO

    > The possibility to
    > suppress the output of the automatically prepared sections for
    > Copyright/License and Authors should allow for writing own sections without
    > dropping <authorgroup> or <copyright> or <legalnotice> in the source. So
    > users are free to choose, if automatically prepared section will be created
    > (default) or if they write their own sections.

    OK, yeah, I can see that definitely makes a lot of sense. I'll add some
    params to do what you suggest, but the names will likely be *.enabled for
    consistency with the convention I've tried to follow and used for some
    already existing params.

     
  • Michael(tm) Smith

    Logged In: YES
    user_id=118135
    Originator: NO

    A change for this issue has been added to the current codebase.
    Please test the change with the latest snapshot from:

    http://docbook.sourceforge.net/snapshots/

     
  • Michael(tm) Smith

    • status: open --> open-fixed
     
  • Michael(tm) Smith

    Logged In: YES
    user_id=118135
    Originator: NO

    Daniel,

    Added the params man.authors.section.enabled and man.copyright.section.enabled.

    Thanks for your persistence on this one. As I've said before, you bug reports and feature requests have been the cause of a number of significant improvements to the manpages output, so I very much appreciate it.

    --Mike

     
  • Michael(tm) Smith

    • status: open-fixed --> pending-fixed
     
  • SourceForge Robot

    Logged In: YES
    user_id=1312539
    Originator: NO

    This Tracker item was closed automatically by the system. It was
    previously set to a Pending status, and the original submitter
    did not respond within 14 days (the time period specified by
    the administrator of this Tracker).

     
  • SourceForge Robot

    • status: pending-fixed --> closed-fixed