[kde-doc-english] kde4_create_manpage and translations

[Chusslove Illich]

On Saturday, 23. February 2013. 15.20.31 David Faure wrote:
> This cmake macro converts docbook to man pages. It depends on kdoctools 
> though, so it creates an unwanted dependency, for low-level frameworks.
> 
> Do we have to use docbook as the source for man pages? I presume this was done 
> to ease translations... but I wonder, how other projects outside KDE handle 
> this? Surely man pages can be translated directly, provided the correct 
> scripting around gettext?
> 
> To make clear what we're talking about:
> 
> checkXML/man-checkXML.1.docbook
> kbuildsycoca5/man-kbuildsycoca5.8.docbook
> kconfig_compiler/man-kconfig_compiler.1.docbook
> kcookiejar4/man-kcookiejar4.8.docbook
> kde5-config/man-kde5-config.1.docbook
> kded5/man-kded5.8.docbook
> kdeinit5/man-kdeinit5.8.docbook
> kdeoptions/man-kdeoptions.7.docbook
> kjscmd/man-kjscmd.1.docbook
> kjs/man-kjs.1.docbook
> kross/man-kross.1.docbook
> makekdewidgets/man-makekdewidgets.1.docbook
> meinproc4/man-meinproc4.8.docbook
> preparetips/man-preparetips.1.docbook
> qtoptions/man-qtoptions.7.docbook
> 
> This is all about man pages, not about docbook->html for user documentation in 
> khelpcenter.
> 
> I tried looking into other source packages (for user-facing binaries, not libs 
> which usually have english-only man pages anyway), but lame-3.98.4 has an 
> english-only man page too.
> Looking at Qt's tools for inspiration: I see no man pages for uic, moc, etc.
> Hmm. And the man-pages-fr package has very very little binaries: only ldd, and 
> time in man1. I wonder if there's really a point in a KDE solution for 
> translated man pages, when nobody else is doing it...
> 
> There's of course one solution to keep the current docbook sources: moving 
> them all into the (future) kdoctools framework. Not very modular, but solves 
> the dependency issue.
> 
> 

I always think it is bad to separate documentation from the source it is
documenting, even more so for something like man pages.

Whether to provide for translation of man pages is a choice that the
maintainer of a piece of code should make, just like for any other end-user
visible text. Where I would be a maintainer, I would provide for translation
of all such text. In which format a piece of end-user visible text is
written is also upon the maintainer. Since in this case there is no clear
maintainer, I think it would be bad either to convert man page sources from
Docbook to something else, or to decide that they should not be translated.

To fix the immediate problem with dependencies, I would let every man page
Docbook remain within its framework, but disabled for building.

Some time later, kdoctools should be split into meinproc, which can be
converted to Qt-only (I think it uses only startup-type K* classes), and the
IO slaves. Or IO slaves can become part of something else, e.g. in
kde-runtime. When meinproc is Qt-only and ready, building of man page
Docbooks in respective frameworks can be reenabled.

-- 
Chusslove Illich (Часлав Илић)
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 197 bytes
Desc: This is a digitally signed message part.
URL: <http://mail.kde.org/pipermail/kde-doc-english/attachments/20130225/7d0ab26c/attachment.sig>