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

[Burkhard Lück]

Am Samstag, 22. Juni 2013, 16:03:26 schrieb 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?
> 
This markup is not wrong for visual reasons, so I'd prefer not to switch off
on libs level, so the unnecessary markup is obvious reading docs in 
khelpcenter.

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

> > 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_Soft
> > ware_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)?
> 
No, let us better concentrate on important content fixes until the release.

We have to live anyway with these entities in kdelibs until the last doc 
translation team has adopted their docbooks.

First we should decide what needs to be improve in the fundamentals regarding 
these topics, the we can start to remove the appendices.
And we have to decide where and how to add this as link to the application 
docbooks.

But as with "EBN only fixes" I'd prefer to do that together  
with proofreading/updating/improving a docbook.

Thanks.

-- 
Burkhard Lück