[kde-doc-english] question about man page docbook file

[Burkhard Lück]

	Am Donnerstag, 29. Juli 2010, um 19:06:05 schrieb Jack:
> On 2010.07.26 03:43, Burkhard Lück wrote:
> > Am Sonntag, 25. Juli 2010, um 22:18:29 schrieb Jack:
> [snip]
> 
> > hmm there is no <othercontrib> in kde docbooks, I guess you mean
> > <othercredit ...> and/or <contrib>?
> > http://l10n.kde.org/docs/doc-primer/book-and-bookinfo.html gives some
> > hints how to use that.
> 
> Sorry - I did mean <othercredit> and <contrib>.  Is there much
> difference between the role attribute and the contrib tag, other than
> that the latter can be more descriptive?
> 
AFAIK no.

> >> For KMyMoney, the copyright is "The KMyMoney Development Team" not
> >> the individual developers.
> > 
> > Afaik  "The KMyMoney Development Team" cannot hold copyrights, since
> > that is not a legal entity, but IANAL.
> 
> You are probably correct, but I don't think we'll solve this in time
> for 4.5.  Also, it looks like the copyright notices in the individual
> program files do list the individual developers.
> 
> > Please ask on the kde-licensing list where real lawyers read. There
> > is this page on techbase
> > (http://techbase.kde.org/Policies/Licensing_Policy), but techbase is
> > down at the moment.
> 
> All it requires is that the copyright holder be listed, along with an
> email address for contact.  However it really just mentions the code
> files, not how it's listed in the documentation.  However, I've asked
> on the KMM developer list, and they agree to change to list the
> individual developers.  However, that means I will need to extract the
> copyright from each code file, so I'll defer to after the release.
> For now, would it be best to leave it as is, or request a change to
> "members of The KMyMoney Development Team?"
> 
I was apparentlyslightly  wrong here. Please read this thread about the 
copyright notice inthe about dialog:
http://lists.kde.org/?l=kde-licensing&m=128014962632296&w=2

Short summery quoted from on of the mails in that thread:
"it was decided a while back that we don't care about whether the copyrights 
in about dialogs are meaningful, since they can't hope to encompass everyone 
who holds copyrights on the application code or any of the libraries it is 
linked to; the copyright headers in the source files are the important ones."

Applying that to the copyright notice in the documentation I'd say:

For the application copyright notice it does not really matter what you write 
here, you can use Copyright kmymoney 200x-200y The KMyMoney Development Team.

But for the documentation copyright each individual holder has to be named 
like:
Documentation [Chapter foo] Copyright year1, year2,... firstbame surname

> >>>> However, is this also the case in the man page, or are these
> >>>> authors really the authors of the software?
> >>> 
> >>> The authors of the software, because the man pages are only the
> >>> docbook format from the output of appname --help, there is no
> >>> documentation author.
> >> 
> >> Well, for KMyMoney, the man page and --help are not quite the same.
> >> I suppose we could make them match, but not before the string freeze
> >> tonight.  (That's why I'm in such a rush....)
> > 
> > I'd say as long as they don't contradict each other, there is no need
> > to sync them.
> 
> It would be nice to have them the same, but obviously not a high
> priority.
> 
> > If the man page is not only the conversion of app --help output to
> > docbook and has additional infos I'd say the author of these
> > additional infos should be added to the author section.
> 
> Not really additional information, but different options happen to be
> listed.
> 
> >>> There are some historical reasons for these manpages (debian
> >>> has/had a rule that every app must have a man page). And these man
> >>> pages should be properly displayed by the man kioslave in kde.
> 
> I think I'll simply add a future low priority task for the  KMM team to
> make the --help and man page have the same info.
> 
> [snip]
> 
> > > > Thanks for asking all these question.
> > > 
> > > Thanks for answering them.
> > > 
> >>> They help us to update our outdated info (miss your br wrt the
> >>> "tags we do not use" issue) and fill the archivs of this ML with
> >>> usefull infos.
> >> 
> >> I haven't filed it yet, but I'm keeping the email until I get to in
> >> in the next days - once I recover my sleep after the KMyMoney string
> >> freeze.
> > 
> > No need to rush, I only want to avoid that this issue is forgotten.
> 
> As you saw, I filed the bug yesterday.
> 
> >> Also, perhaps I'll be able to provide some help before the KDE
> >> freeze - or is it too close? (I have not yet subscribed to the list
> >> to know that, but it's on my list to do.)
> > 
> > Help is really appreciated, first step is to update the everything in
> > http://l10n.kde.org/docs/, you find that stuff in
> > trunk/www/areas/l10n/docs in kde's svn repo, but you can't commit
> > there. This directory has restricted write access.
> 
> If I work on that, how would I submit changes?  Email the output of
> "svn diff" to this list? (yes, I'll hold any edits until after the 4.5
> release)
> 
Send a svn diff to this list or directly to me.

There is no string freeze rule for that stuff.

But there is more to do than just fixing some errors:

* identifiy what is really used, up to date? usefull? better on techbase?

* not used stuff, use it where, update needed, remove it?

* duplicated documentation in trunk/www/areas/docs/doc-primer and 
trunk/www/areas/docs/markup, split of the common part to a separate docbook to 
make maintaining easier, check + update it, fix errors like the incomplete list 
"tags we do not use".
 
Nicolas Ternisien <nicolas.ternisien at gmail.com> is the webmaster for that 
documentation.
About the regeneration process itself, it uses
scripts/mkdocs/mkdocs.php script from the l10n.kde.org folder.

Thanks.

-- 
Burkhard Lück