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

[Yuri Chornoivan]

Hi,

написане Sat, 22 Jun 2013 13:09:03 +0300, Burkhard Lück  
<lueck at hube-lueck.de>:

> 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.

I agree, but the bold and backgrounf in titles can be easily switched off  
on libs level to not break the current strings. Does it make sense?

> 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.

It is nice to have exact capitalization while translating. No the other  
hand, if the documentation writer is sure about what should be the best  
for the style, I'd better leave the decision to the writer.

>
> 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 useful 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>

No objections to these changes. Should we do them now (~2 weeks to freeze)?

>
> Comments please.
>
> Thanks.
>

Thanks for your work.

Best regards,
Yuri