[kde-doc-english] kde4_create_manpage and translations

[Albert Astals Cid]

El Dilluns, 25 de febrer de 2013, a les 11:36:43, Chusslove Illich va 
escriure:
> 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.

meincproc already has a Qt only version (meinproc_simple)

Cheers,
  Albert