From kde-doc-english  Sat Jun 22 10:09:03 2013
From: Burkhard =?ISO-8859-1?Q?L=FCck?= <lueck () hube-lueck ! de>
Date: Sat, 22 Jun 2013 10:09:03 +0000
To: kde-doc-english
Subject: [kde-doc-english] Style/Markup and Content issues with our docbooks
Message-Id: <2474226.VGyzbcgeVq () parodia>
X-MARC-Message: https://marc.info/?l=kde-doc-english&m=137189575801434

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 o=
n =

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 a=
n =

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 strin=
gs, =

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=3D"installation">
<title>Installation</title>
<sect1 id=3D"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=3D"compilation">
<title>Compilation and Installation</title>
&install.compile.documentation;
<para>For detailed information on how to compile and install &kde; =

applications see <ulink =

url=3D"http://techbase.kde.org/Getting_Started#Building_and_Running_KDE_Sof=
tware_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 th=
e =

&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 anymor=
e =

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, y=
ou =

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 2=
8x)
<para>This document may have been updated since your installation.
You can find the latest version at <ulink
url=3D"http://docs.kde.org/">http://docs.kde.org/</ulink>.</para>

Comments please.

Thanks.

-- =

Burkhard L=FCck
_______________________________________________
kde-doc-english mailing list
kde-doc-english@kde.org
https://mail.kde.org/mailman/listinfo/kde-doc-english