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
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?
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.
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
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.
Logged In: YES
user_id=118135
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
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?
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
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.
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.
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/
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
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).