[kde-doc-english] Linking to Support Resources/Changing the Docs Footer

[Luigi Toscano]

Hi,

sorry for the late answer, I was (partly) on vacations. Few answers (as
expected) below.

Burkhard Lück wrote:
> Am Samstag, 1. Juni 2013, 13:39:17 schrieb T.C. Hollingsworth:
>> On Sat, Jun 1, 2013 at 9:22 AM, Burkhard Lück <lueck at hube-lueck.de> wrote:
>>> Am Mittwoch, 29. Mai 2013, 21:33:26 schrieb T.C. Hollingsworth:

>>>> I'd like to add a new chapter to the KDE Fundamentals documentation
>>>> that includes two things:
>>>>
>>>> 1. A list of resources for getting further assistance with KDE,
>>>> linking to the KDE forums, appropriate mailing lists, bugzilla, etc.
>>>
>>> That's partly opverlapping with the Online Help docbook?
>>
>> Oh, right; I forgot about that one.  Should we make changes to this
>> DocBook instead?  Or maybe merge it into Fundamentals?
>>
> I'd like to keep the Online Help docbook as first top level entry in 
> KHelpcenters navigation tree. 
> And it should not be overloaded with resources for getting further assistance 
> with KDE, appropriate mailing lists, bugzilla, etc., That should be in 
> fundamentals.
Yes, but a bit more of offline documentation wouldn't hurt (even if I'm the
first one who does not like duplicated information).

> 
>>>> 2. A brief overview of how to submit feedback to KDE Documentation
>>>> Team, including this e-mail address
>>>>
>>>> We could then change the footer in kdelibs.git to read something like
>>>> this:
>>>>
>>>> For further assistance using this or any other KDE application, see
>>>> _Getting Help_. <help:/fundamentals/support.html>
>>>> Would you like to make a comment or contribute an update to this page?
>>>>
>>>>  See _Contacting the Documentation Team_.
>>>>
>>>> <help:/fundamentals/support.html#docs>
>>>
>>> That footer text seems to be much too long, it should be much shorter so
>>> it
>>> doesn't occupy much screen space.
>>> But given the behavior of people using the link in the footer we have now
>>> (either they don't read or understand the text or simply ignore its
>>> content) I doubt, if it really helps offering two links.
>>
>> I guess we could shorten this to the first sentence, then?  Any
>> suggestions for revising this would be most welcome, I'm not entirely
>> happy with that text.
>>
> "A comment or contribution to this page? Mail kde-doc-english at kde.org
> Further assistance using KDE applications, see _Getting Help_. 
> <help:/fundamentals/support.html>"
> I'm not really satisfied with this proposal:(

Maybe swap the two as in the first proposal (keeping it short), as most of the
people would (like to) use the first link (help on KDE applications).
Or do people read the last sentence only? :)


>>>> One other thing I think would be awesome if we do this would be to
>>>> find a way to also provide a way for translators to fill in a section
>>>> of this new chapter that explains how to get support in their
>>>> language.
>>>
>>> Yes that would be a good addition.
>>>
>>>> Doesn't the translation framework treat <!--TRANS:foo--> type comments
>>>> specially?  Would it be possible to add a
>>>> <!--TRANS:LANGUAGE_SUPPORT_INFO--> comment or some such to the
>>>> relevant chapter in fundamentals, and instruct translators to fill in
>>>> that message with a sectN with useful information for their language.
>>>>
>>>> For instance, the Spanish translator(s) would translate that message
>>>> to something like this:
>>>> <sectN id="support-lang">
>>>> <title>Obtención de Ayuda en Español</title>
>>>> <para>Para obtener ayuda para usar las aplicaciones de &kde; en
>>>> español, por favor escriba <ulink
>>>> url="mailto:general at kde-espana.es">general at kde-espana.es</ulink> a
>>>> través de correo electrónico.</para>
>>>> </sectN>
>>>>
>>>> This would of course be optional, and if translators don't want to/are
>>>> unable to because such resources don't exist no section like this will
>>>> appear.  (This also would prevent a "Getting Help in English" section,
>>>> which doesn't make much sense.)
>>>
>>> Technically this should work, but tosky of course will know better.
>>
>> Should I ask kde-i18n-doc?
>>
> Luigi Toskano (tosky) is subscribed here.

But I don't know how the conversion script (docbook -> po) works. But from the
code it seems, as T.C. pointed out, that it can handle any comment of the type
<!-- TRANS:THIS_IS_A_SPECIAL_COMMENT -->
which is changed as
<trans_comment>THIS_IS_A_SPECIAL_COMMENT</trans_comment>.

We can... try :)


Ciao
-- 
Luigi