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

[Burkhard Lück]

Am Sonntag, 25. Juli 2010, um 22:18:29 schrieb Jack:
> On 2010.07.25 15:57, Burkhard Lück wrote:
> > Am Sonntag, 25. Juli 2010, um 20:25:17 schrieb Jack:
> > > How connected to index.docbook is man-app.1.docbook?
> > 
> > Only via kdelibs/kdoctools/customization/
> > 
> > > First, can I use author entities defined in index.docbook here?
> > 
> > No.
> > 
> >> I would hope so, but since it's neither of these files directly
> >> refers to the other, I would guess not.  (These entities have just
> >> been defined, so they are not yet available in kdelibs.)
> >> 
> >> Second, as I understand it, in index.docbook, the "authors" are the
> >> authors of the documentation, not the authors of the software,
> > 
> > Yes
> > 
> >> who would be listed as <othercontrib>
> > 
> > No
> 
> So if not for the developers (and graphics designers, etc.) what would
> <othercontrib> within <authorgroup> be used for?
> 
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.

> > > and also in credits.docbook.
> > 
> > Yes, "appname copyright xyz"
> 
> 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.

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.

> >> 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 als long as they don't contradict each other, there is no need to sync 
them.

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.

> > 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.
> > 
> > Afaik I have converted some man pages via a script (don't remember
> > the name actually) to docbook and introduced into kde svn).
> > 
> > In case you need any help converting from man to docbook format. just
> > drop me a note.
> 
> I don't know when or how it was done, but our man page is already
> man-kmymoney.1.docbook and the reverse conversion is part of the
> cmake/make process (which you already know).
> 
> > 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.

> 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.

-- 
Burkhard Lück