[kde-doc-english] Style/Markup and Content issues with our docbooks

[Burkhard Lück]

Hi,

I'd like to discuss some style/markup and content issues with our docbooks.

1) Style/Markup

1a) We should not use <gui...> markup in title, has no meaning here.

1b) 
<quoting docbook primer>Take care that the text exactly matches the label on 
screen. If it has a : on the dialog box, put the : into your documentation. 
Match the capitalization. 
</quoting docbook primer>
>From my pov this rule is too strict (and I am guilty having ignored the 
capitalization rule updating docbooks because that effects many translation 
teams). 
I have mainly three issues with this rule:
* An ellipsis at the end of an guimenuitem makes sense in the GUI string, 
indicating that it is not direkt action, but acquires user input, e.g. in an 
appearing dialog, but in the documentation the ellipsis has no meaning.
* Writing a guilabel with a ":" in a sentence looks strange and disturbs 
the readability
* KDE3 afair had a strict style guide about capitalization in the gui strings, 
but in kde4 this got somehow lost. So I'd won't be too strict here, and of 
course never change only capitalization in a docbook without content change.

2) Content issues:

Most but not all documentations have an appendix with sections about 
Installation, How to obtain &kapplication;, Compilation and Installation

<appendix id="installation">
<title>Installation</title>
<sect1 id="getting-kapp">
<title>How to obtain &kmyapplication;</title>
&install.intro.documentation;
<para>&kappname; is part of the &kde; project &kde-http;.</para>
<para>&kappname; can be found in the &package; package on &kde-ftp;, 
the main &FTP; site of the &kde; project.</para>
</sect1>
<sect1 id="compilation">
<title>Compilation and Installation</title>
&install.compile.documentation;
<para>For detailed information on how to compile and install &kde; 
applications see <ulink 
url="http://techbase.kde.org/Getting_Started#Building_and_Running_KDE_Software_From_Source">
Building and Running KDE Software From Source</ulink></para>
<para>Since &kde; uses <command>cmake</command> you should have no 
trouble compiling it. Should you run into problems please report them to the 
&kde; mailing lists.</para>

In general I am in favor to skip these appendix sections for the following 
reasons:

* The package concept does not work any more due to the splitted modul 
repositories in git, there is e.g. no package kdenetwork or kdeadmin anymore 
on the kde ftp server.

* The info provided is way too generic and not sufficient.

* Our target user is obviously installing kde from distribution packages, you 
can see that on bugs.kde.org or in forum posts.

So I'd like to replace the appendix sections with a link to fundamentals.

Another usefull entity is perhaps &updating.documentation; (but used only 28x)
<para>This document may have been updated since your installation.
You can find the latest version at <ulink
url="http://docs.kde.org/">http://docs.kde.org/</ulink>.</para>

Comments please.

Thanks.

-- 
Burkhard Lück