KDE User Guide outdated?

[Jonathan Jesse-3]

Was looking at the help system the other day and noticed how out of date the KDE User Guide is.  Is it worth taking a look at updating this guide as a big project?  Or should I just move on?

Jonathan

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

[Arturo Silva]

On Tue, Sep 15, 2009 at 9:55 PM, Jonathan Jesse <jjesse@...> wrote:
> Was looking at the help system the other day and noticed how out of date the
> KDE User Guide is.  Is it worth taking a look at updating this guide as a
> big project?  Or should I just move on?

Hi there.  :)

Ah!  Would that by any chance be the document that, at least in my
distribution, reads:  "Revision 0.0.1 (2004-06-16), Copyright © 2004,
2005 The KDE Documentation Team"?  :)

Yeah, I think that looks... just a wee bit outdated.  :D

It's also fairly large, though, so not something that can be updated
overnight unless divided up between various people.  There's plenty of
screenshots that can be updated, though not unfortunately all of them
can be without first updating the adjacent text (e.g., the File
Manager section naturally pours over Konqueror instead of Dolphin).
_______________________________________________
kde-doc-english mailing list
kde-doc-english@...
https://mail.kde.org/mailman/listinfo/kde-doc-english

[Arturo Silva]

Hello again,

I've actually been learning a bit more about how the SVN repositories
worked and successfully managed to find where the User Guide is stored
at in KDE4's trunk repository.

Here it is using the WebSVN viewer:

http://websvn.kde.org/trunk/KDE/kdebase/runtime/doc/userguide/

The actual files can be downloaded to your computer either by using
this command in the test directory of your choice:

     svn co -N svn://anonsvn.kde.org/trunk/kdebase/runtime/doc

Or by opening svn://anonsvn.kde.org/trunk/kdebase/runtime/doc in the
KDESVN graphical client (as seen in the attached).

The actual helpcenter manuals are stored here in your system:

     /usr/share/doc/kde/HTML/en/khelpcenter

About the only thing I have not figured out yet is how to edit the
DocBook files graphically or how to open them without overwriting the
existing DocBooks.  Hopefully someone can chime in there.

===============

That issue aside, updating the User Manual (or for that matter the
Quick Start Guide or Visual Dictionary) does look more and more
possible, although clearly this is still a long-term thing.  If there
are no objections, I wouldn't mind at least starting to update a few
of these pages.  I figure it would be good practice for doing SVN
commits and the like, and maybe to learn more things about KDE4 that I
may have never noticed before.

Some thoughts on the matter would be appreciated. Thanks!


--Arturo "C-quel" Silva


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

[Yuri Chornoivan]

На Fri, 18 Sep 2009 04:26:16 +0300, Arturo Silva <jasilva28@...>  
написав:

Hi!
> About the only thing I have not figured out yet is how to edit the
> DocBook files graphically or how to open them without overwriting the
> existing DocBooks.  Hopefully someone can chime in there.
>
You can try Syntext Serna Free (it is open source WYSIWYG XML editor).

http://www.syntext.com/products/serna-free/

Best regards,
Yuri
_______________________________________________
kde-doc-english mailing list
kde-doc-english@...
https://mail.kde.org/mailman/listinfo/kde-doc-english

[Arturo Silva]

On Fri, Sep 18, 2009 at 1:45 AM, Yuri Chornoivan <yurchor@...> wrote:
>
>
> You can try Syntext Serna Free (it is open source WYSIWYG XML editor).
>
> http://www.syntext.com/products/serna-free/
>

Aaaah!  Eureka!  This looks nice!  ^__^b

Course since you brought it up, I guess I'll take that as one vote
that for "Yes", it's okay for me to try updating the User Manual. Now
I'm hopeful.  ^___^v

Just so I don't get too ambitious at first (I am a bit sick at the
moment), I figure I'll try updating the Visual Dictionary first.
Maybe by end of next week.  ^^b


--Arturo
_______________________________________________
kde-doc-english mailing list
kde-doc-english@...
https://mail.kde.org/mailman/listinfo/kde-doc-english

On Tue, Sep 15, 2009 at 09:55:25PM -0400, Jonathan Jesse wrote:
> Was looking at the help system the other day and noticed how out of date the
> KDE User Guide is.  Is it worth taking a look at updating this guide as a
> big project?  Or should I just move on?
>
> Jonathan

I have this on my TODO list, but I would be more than happy for you to help
out on it, or if you want to, take it on. You know what to do, and yes it
is definitely worth it.

--
 Name|  Richard JOHNSON
Title|  Developer
  WWW|  http://kde.org
Email|  rjohnson@...
GnuPG|  3578 0981 A21D D662 2A96  7623 F4C1 838C D8C4 4738
 Home|  http://www.nixternal.com


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

[Arturo Silva]

On Fri, Sep 18, 2009 at 11:52 PM, Richard JOHNSON <rjohnson@...> wrote:
>
> I have this on my TODO list, but I would be more than happy for you to help
> out on it, or if you want to, take it on. You know what to do, and yes it
> is definitely worth it.

Hi!  Sure, I'd love to at least try -- there's certainly nothing to be
lost in trying, other than that I'd save you the work of doing some of
the screenshots!  :P

I don't want to overestimate my capacity (as I am relatively new), so
I will certainly start small with the Visual Dictionary first, and
then maybe the Quick Start.  If those go well, then I'll be happy to
help you with the big fish.  :D


--Arturo
_______________________________________________
kde-doc-english mailing list
kde-doc-english@...
https://mail.kde.org/mailman/listinfo/kde-doc-english

[Burkhard Lück]

Am Samstag 19 September 2009 05:58:54 schrieb Arturo Silva:

> On Fri, Sep 18, 2009 at 11:52 PM, Richard JOHNSON <rjohnson@...> wrote:
> > I have this on my TODO list, but I would be more than happy for you to
> > help out on it, or if you want to, take it on. You know what to do, and
> > yes it is definitely worth it.
>
> Hi!  Sure, I'd love to at least try -- there's certainly nothing to be
> lost in trying, other than that I'd save you the work of doing some of
> the screenshots!  :P
>
> I don't want to overestimate my capacity (as I am relatively new), so
> I will certainly start small with the Visual Dictionary first, and
> then maybe the Quick Start.  If those go well, then I'll be happy to
> help you with the big fish.  :D
>

Yep, updating Visual Dictionary + Quick Start with new screenshots is a good
start for the kdebase docs.

Please go ahead.

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

On Fri, Sep 18, 2009 at 11:58:54PM -0400, Arturo Silva wrote:
[...]
> Hi!  Sure, I'd love to at least try -- there's certainly nothing to be
> lost in trying, other than that I'd save you the work of doing some of
> the screenshots!  :P

That would be awesome! and greatly appreciated.

> I don't want to overestimate my capacity (as I am relatively new), so
> I will certainly start small with the Visual Dictionary first, and
> then maybe the Quick Start.  If those go well, then I'll be happy to
> help you with the big fish.  :D

Do not hesitate to ask any questions here or join us in #kde-docs on IRC.
You can get a hold of someone every now and then in there :)

--
 Name|  Richard JOHNSON
Title|  Developer
  WWW|  http://kde.org
Email|  rjohnson@...
GnuPG|  3578 0981 A21D D662 2A96  7623 F4C1 838C D8C4 4738
 Home|  http://www.nixternal.com


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

[Jonathan Jesse-3]

On Sun, Sep 20, 2009 at 12:33 PM, Richard JOHNSON <rjohnson@...> wrote:

On Fri, Sep 18, 2009 at 11:58:54PM -0400, Arturo Silva wrote:
[...]

> Hi!  Sure, I'd love to at least try -- there's certainly nothing to be
> lost in trying, other than that I'd save you the work of doing some of
> the screenshots!  :P

That would be awesome! and greatly appreciated.

> I don't want to overestimate my capacity (as I am relatively new), so
> I will certainly start small with the Visual Dictionary first, and
> then maybe the Quick Start.  If those go well, then I'll be happy to
> help you with the big fish.  :D

Do not hesitate to ask any questions here or join us in #kde-docs on IRC.
You can get a hold of someone every now and then in there :)

--
 Name|  Richard JOHNSON
Title|  Developer
 WWW|  http://kde.org
Email|  rjohnson@...
GnuPG|  3578 0981 A21D D662 2A96  7623 F4C1 838C D8C4 4738
 Home|  http://www.nixternal.com

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (GNU/Linux)

iQIcBAEBAgAGBQJKtllQAAoJEPTBg4zYxEc4zLMP/3yroUxCkcNgZDxn60LL814t
lKUvd8zDB/Pf1xNYKjqhoCavLENZ0ZGU9k6MndzxweDZZXIjfolvyIdUv7lenayi
3DAMf3LYpeOlHLjfxh63BPru34UPt4IGgr05H5nzIKr4LELTRi/igfGYfiqDDwVd
cK9o/VOS9yhxRI07bynciquFrggIxagrbq2yH6fu89RhLL2FNMjVdAikz/9pDBON
e/6NbP4rroEAD1hNZPmWv7tfAYHgI34FiTO+C0ou6BfE3V9Wl5RvV7B6plDCFL8X
gO1GtA1DL22GDJQlzjlVPe33NFmnW2IamRs2yTDFi0ZW0NXX4neLTGHCxluezy6U
tI/pXF5IxPnaSMHvew/Um0QLpf9YvpkDAeRHpEmDrVvOdByjmkm+Gz2EzUd18m3X
yk77m2lZ9fq3ZdHI7O1QmCyetwgiatrvrlCxvX4sIP/NuV9/65SAHUQwC2k5rtMy
N8oaBKRkey7nnupCh0FYuFGGE+D3DBxvFPYnj7BvDEqOH6IjFIIO1k4TSjBnv/rk
b4jJuM+abCEWOBGawUrTVWbUKNWUh+tDRsw5uosd2CypPry/G1Y+FhnejwYJqLbn
iwN5hZQxZIgjNTyAj7BEpbHs6aYZS6ZXr5uVIIiSCiWtan02l1eVJNE+H1E2f7ex
w+hWAkC3ctdMhDa6UB6t
=pBX9
-----END PGP SIGNATURE-----

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

Volunteering my service on this as well, is there a wiki we could start dividing up the sections that need to be updated and get this rockin and rolling.

Jonathan

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

[Arturo Silva]

On Sat, Sep 19, 2009 at 1:37 PM, Burkhard Lück <lueck@...> wrote:
>
> Yep, updating Visual Dictionary + Quick Start with new screenshots is a good
> start for the kdebase docs.
>
> Please go ahead.

And that's two votes!  Thank ye, I'll go ahead with it then.  I'll aim
for a Friday release, although I should warn I'm also assisting the
Oxygen team, as well as one or two KDE game projects too.  I guess I
got too overzealous with my first contributions. ^^'


On Sun, Sep 20, 2009 at 12:33 PM, Richard JOHNSON <rjohnson@...> wrote:
>
> Do not hesitate to ask any questions here or join us in #kde-docs on IRC.
> You can get a hold of someone every now and then in there :)
>

Ooh, I'm usually full of hesitation when it comes to IRC (can't really
afford much schedule disruption, especially if I get engrossed in chat
sessions).  But I will keep that in mind once I start getting a little
more active -- right now I feel I'm barely getting warmed up.  ^^


On Sun, Sep 20, 2009 at 9:17 PM, Jonathan Jesse <jjesse@...> wrote:
>
> Volunteering my service on this as well, is there a wiki we could start
> dividing up the sections that need to be updated and get this rockin and
> rolling.
>

Hehe, well I personally don't know of one, but you now know where the
guide files are stored at.  I'd say you can start making landfall on
the User Manual itself, and then post your updates here so that they
can load them up for you.  That's probably what I will do until I
learn how to commit these files on my own. ^^


--Arturo
_______________________________________________
kde-doc-english mailing list
kde-doc-english@...
https://mail.kde.org/mailman/listinfo/kde-doc-english

[Burkhard Lück]

Am Montag 21 September 2009 03:17:21 schrieb Jonathan Jesse:
 >
 > Volunteering my service on this as well, is there a wiki we could start
> dividing up the sections that need to be updated and get this rockin and
> rolling.
>
The userguide is already divided into 49 docbooks in the svn archiv  
(http://websvn.kde.org/trunk/KDE/kdebase/runtime/doc/userguide/).

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

[Arturo Silva]

Well, after wasting a little bit of time and being relatively
unimpressed by the [very few] WYSIWYG editors that [presumably]
support the DocBook format, I finally decided to simply edit the
DocBook files manually using good ol' fashioned Kwrite.  It brought
back good ol' memories of my old HTML days.  ^__^

The only problem was that I still couldn't figure out how to actually
READ the DocBook files using a standalone application that wasn't
KHelpCenter.  Not having luck with that, I ended up making
/usr/share/doc/kde/HTML/en/khelpcenter read-write, backing the
original contents up somewhere, and then making all the new changes
directly to the files.  That way, i could follow my changes regularly
by swapping back and forth between pages in KHelpCenter -- very crude,
but got the job done.  ;)

----

I started with the KDE Viisual Dictionary as promised and for the most
part modernized all the example screenshots.  However, I also did some
edits to the introductory text and presentation as well, since my goal
(now that I know what I can do) is to MERGE the Quick Start Guide with
the Visual Guide, making it a Visual Quick Start Guide of sorts that
more-or-less fulfills the original goal of creating a graphical tour
of KDE.

For the moment, please review my work on the Visual Dictionary:

http://pigux.com/kde4/documentation/visualguide_2009-0927.zip


Thanks!


--Arturo "C-quel" Silva
_______________________________________________
kde-doc-english mailing list
kde-doc-english@...
https://mail.kde.org/mailman/listinfo/kde-doc-english

[Yuri Chornoivan]

Hi!

На Sun, 27 Sep 2009 07:56:48 +0300, Arturo Silva <jasilva28@...>  
написав:

> Well, after wasting a little bit of time and being relatively
> unimpressed by the [very few] WYSIWYG editors that [presumably]
> support the DocBook format, I finally decided to simply edit the
> DocBook files manually using good ol' fashioned Kwrite.  It brought
> back good ol' memories of my old HTML days.  ^__^
>
> The only problem was that I still couldn't figure out how to actually
> READ the DocBook files using a standalone application that wasn't
> KHelpCenter.  Not having luck with that, I ended up making
> /usr/share/doc/kde/HTML/en/khelpcenter read-write, backing the
> original contents up somewhere, and then making all the new changes
> directly to the files.  That way, i could follow my changes regularly
> by swapping back and forth between pages in KHelpCenter -- very crude,
> but got the job done.  ;)
>

You can use Kate with Konsole (Window->Tool Views->Show Terminal) KPart.

Just enter in command line (after the corresponding directory change):  
meinproc4 your_docbook && konqueror index.html
and you will see docbook HTML version in Konqueror.

When you make changes in docbook issue the command meinproc4 your_docbook  
again and push F5 in Konqueror.

Hope this helps,
Yuri
_______________________________________________
kde-doc-english mailing list
kde-doc-english@...
https://mail.kde.org/mailman/listinfo/kde-doc-english

[Arturo Silva]

On Sun, Sep 27, 2009 at 2:26 AM, Yuri Chornoivan <yurchor@...> wrote:

>
> You can use Kate with Konsole (Window->Tool Views->Show Terminal) KPart.
>
> Just enter in command line (after the corresponding directory change):
> meinproc4 your_docbook && konqueror index.html
> and you will see docbook HTML version in Konqueror.
>
> When you make changes in docbook issue the command meinproc4 your_docbook
> again and push F5 in Konqueror.
>
> Hope this helps,
> Yuri

hehe, well it certainly helps in that I don't have to stick my nose
into a root directory anymore, so I can continue from the safety of my
home folder. ^^

However, it does seem a bit awkward to have to keep converting this
thing to an HTML file after each change.  Not hard to do, but just
awkward in that it's not already a feature somewhere.

You would think given the importance of our documentation, there'd be
more DocBook tools to help potential new contributors submit their
work.  Having worked with the format this evening, I actually don't
find it that hard (in fact, it's even a little easier than HTML in
some parts), and that's why I don't know for the life of me why there
are so few WYSIWYG editors and even viewers that work exclusively with
this format.

I'd hope that creating a simple DocBook viewer for KDE4 wouldn't be
any harder than taking KHelpCenter and adding on a few extra menu
options and maybe Kate integration.  Maybe an actual Dev can prove me
wrong, but it's just something that's been on my mind.  ;)


--Arturo "C-quel" Silva
_______________________________________________
kde-doc-english mailing list
kde-doc-english@...
https://mail.kde.org/mailman/listinfo/kde-doc-english

[Anne Wilson-5]

On Friday 18 September 2009 06:52:56 Arturo Silva wrote:

> On Fri, Sep 18, 2009 at 1:45 AM, Yuri Chornoivan <yurchor@...> wrote:
> > You can try Syntext Serna Free (it is open source WYSIWYG XML editor).
> >
> > http://www.syntext.com/products/serna-free/
>
> Aaaah!  Eureka!  This looks nice!  ^__^b
>
> Course since you brought it up, I guess I'll take that as one vote
> that for "Yes", it's okay for me to try updating the User Manual. Now
> I'm hopeful.  ^___^v
>
> Just so I don't get too ambitious at first (I am a bit sick at the
> moment), I figure I'll try updating the Visual Dictionary first.
> Maybe by end of next week.  ^^b
>

There has been quite a lot of talk about the relative simplicity of wiki

editing, but of course the need then is for import and export.  Burkhard Lück
identified a mediawiki extension -
http://www.mediawiki.org/wiki/DocBook_XML_export - and I've put in a request
to sysadmins to have this installed (bug #205912).  As you know, sysadmins are
always overworked, so if anyone feel they can help with this, please add to
the bug report and/or contact danimo.

Anne
--
New to KDE4? - get help from http://userbase.kde.org
Just found a cool new feature?  Add it to UserBase


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

[Burkhard Lück]

Am Sonntag 27 September 2009 06:56:48 schrieb Arturo Silva:

>
> I started with the KDE Viisual Dictionary as promised and for the most
> part modernized all the example screenshots.  However, I also did some
> edits to the introductory text and presentation as well, since my goal
> (now that I know what I can do) is to MERGE the Quick Start Guide with
> the Visual Guide, making it a Visual Quick Start Guide of sorts that
> more-or-less fulfills the original goal of creating a graphical tour
> of KDE.
>
> For the moment, please review my work on the Visual Dictionary:
>
> http://pigux.com/kde4/documentation/visualguide_2009-0927.zip
>

Hi  Arturo,

thanks for your work.

I downloaded your update, but there are a few issues to solve before I can
proofread it:

* index.docbook is broken, does not pass checkXML index.docbook here :-(

* please don't change the folder layout (png's in a subfolder of visualdict,
this breaks the current cmake macro kde4_create_handbook and makes your update
unusable for the english documentation as for all language documentations as
well.

* please send only the changed files (or even just a svn diff). In your zip
archive with a mixture of files from kdelibs and from kdebase/runtime and even
from your distro I can not recognize which files from the svn archiv are
changed and therefore check, if and how your update can be integrated into the
kde system.

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

[Arturo Silva]

On Sun, Sep 27, 2009 at 6:18 AM, Burkhard Lück <lueck@...> wrote:

>
> * index.docbook is broken, does not pass checkXML index.docbook here :-(
>
> * please don't change the folder layout (png's in a subfolder of visualdict,
> this breaks the current cmake macro kde4_create_handbook and makes your update
> unusable for the english documentation as for all language documentations as
> well.
>
> * please send only the changed files (or even just a svn diff). In your zip
> archive with a mixture of files from kdelibs and from kdebase/runtime and even
> from your distro I can not recognize which files from the svn archiv are
> changed and therefore check, if and how your update can be integrated into the
> kde system.
>

Hmm, that is kind of overestimating the extent of my contribution or
what little knowledge I managed to scrape up over the course of the
week regarding this format.  I don't even understand half of what
you're saying (diff?), and I really explained before this is not taken
from the SVN copy nor really meant to be committed back to SVN in its
current form.  All I really need is for it to be reviewed, and then
whoever is knowledgeable enough (and also happens to have an SVN
account) can take the best of my draft copies and apply it to the
trunk copies in a way that doesn't break anything.

If for whatever reason you can't read what I sent you (and welcome to
my world if you can't), then try using the attached HTML copies if you
want.

From what Anne has stated, it sounds like there does seem to be a
consensus that a more human-editable documentation format is at least
sought after -- and while the current format has its merits (it seems
easy to translate), its low level of customization and presentation
seems to put it at odds with the rest of the KDE4 desktop.

So I get the feeling I'm out of my element and will only get in the
way if I continue, so regretfully I will have to pull out of this User
Manual project after all.  While I'll gladly continue to help review
draft documentation if necessary, I want to focus on my projects in
kde-games and kde-artwork where I can make more immediate and less
intrusive contributions that are also better suited to my current
skill set and schedule.

Sorry this didn't work out.  :(
But hey, at least you have 23 less screenshots to worry about, so it
wasn't a total loss.  ;)

Take care.


--Arturo


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