user manuals

[Ian Wadham]

On 06/03/2013, at 1:14 AM, Jeremy Lavergne wrote:
> It's probably better to create subports that install documentation only.
> 
> The original reason these were left off were
> * slowing down an already humongous build cycle (no longer an issue thanks to buildbots)
> * doc building used meinproc4, which routinely crashed and prevented installation (might still be a problem)

Ah, I understand. Well, I think meinproc4 is OK now. Last year I did extensive updates
to some index.docbook files in KDE Games, for the KDE 4.9 and 4.10 releases, and
was able to build and test-proofread them quite easily on a Macbook KDE-dev setup.

meinproc4 is very fast (~ 1 second), so I would suggest the following:

  - Always build the user manual for a KDE port, using the CMakelists.txt file
  - Add a note to the Macports KDE Wiki to show where to find API docs online
  - Discontinue the +docs  variant for KDE ports

My reasons for discontinuing the +docs variant in KDE ports would be:

 - It brings in additional dependencies needed by Doxygen but not by all end-users
 - It acts recursively (if you are not careful or do not know), and could bring in all of
   the Qt doco, which is rather extensive …
- No need for KDE subports ...

What I am suggesting is essentially what Linux distros do, i.e. always supply the
user manual and do not supply the API doco, except perhaps in a -devel binary
package (ie. one with source-code headers for developers to use).

All the best, Ian W.

> On Mar 5, 2013, at 12:01 AM, Ian Wadham wrote:
> 
>> 4. Many KDE apps come with user manuals: should MacPorts install them by default?
>> 
>>   If no, I will add a recommendation to the Wiki to use the +docs variant.  If yes,
>>   is there perhaps some more efficient way for Macports to provide them?
>> 
>>   I am unclear on what variants do exactly (ie. local vs. global).  If I ask for +docs,
>>   do I get it on all the dependencies?
>> 
>>   Also, with +docs I seem to get all the dependencies needed to generate every
>>   possible format of the application's API doco from Doxygen (not required by the
>>   average user).  KDE user manuals are in XML and follow the Docbook convention
>>   and there is a KDE utility to convert them to HTML during build and installation.
>