Message: previous - next
Month: March 2011

Re: [trinity-devel] kdelibs doc common build problem

From: "David C. Rankin" <drankinatty@...>
Date: Sat, 12 Mar 2011 12:41:38 -0600
On 03/12/2011 05:44 AM, Serghei Amelian wrote:
> I don't care very much about documentation, if someone want to pickup this
> task, please do it. I created for this purpose a macro named
> tde_create_handbook() which automated all ugly work. There is not yet any
> support for manual pages (we really need manual pages??).

Documentation and man pages are just as important as the apps themselves. When a 
new user is faced with a new desktop and applications with -- no help -- the 
apps don't mean very much and the new user usually quits and goes back to a 
desktop where he can get help :)

I agree that we get the apps going first, but we will need to swing back through 
and pick up the documentation later. Classic example: yesterday, on suse 11.4, I 
needed to find out how to apply Bash syntax highlighting to the Trinity 
PKGBUILDs for Arch I was working on. If Ilya hadn't included the kate handbook 
in the suse/kde3 release, I would have been hosed. But, since it was there, I 
was able to get the help I needed in seconds with the "KDE Help Center" rather 
than searching for 1/2 hour on the internet weeding though all the posts for 
older versions of kate or those for kde4 kate. Correct documentation makes all 
the difference in the world...

Hopefully when we swing back through to get the documentation working, I'll be 
smart enough on cmake to help :)

> tde_create_handbook() syntax:
> tde_create_handbook(<target>  [FILES file1 files2 ...] [SRCDIR /path/to/src]
> [DESTINATION name_of_app] [LANG language] )
> - FILES are detected automatically, usually
> - SRCDIR is not needed usually (equivalent with "meinproc --srcdir")
> - DESTINATION is name of application, usually; if provided path is not
> absolute, ${HTML_INSTALL_DIR}/en is prepended.
> - LANG - english by default
> Real example:
> ===============
> tde_create_handbook( SRCDIR ${CMAKE_SOURCE_DIR}/kdoctools DESTINATION kspell )
> add_dependencies( kspell-handbook meinproc )
> ===============
> add_dependencies() is needed only in kdelibs context, to ensure that meinproc
> is built before cmake generating documentation (otherwise there is a big
> chance to fail on parallel building).
> Sorry for english, if is something unclear, just ask and I will try to explain
> better.

Serghei -- all of your explanation are GREAT! We want all that you can give us. 
The challenge and difficulty for me is filling in the gaps in understanding I 
have that fall in between the steps you provide. So the more you can provide, 
the better :)

David C. Rankin, J.D.,P.E.