'Re: Kate, question about documentation: can we split it between app/part'

[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kwrite-devel
Subject:    Re: Kate, question about documentation: can we split it between app/part
From:       Christoph Cullmann <cullmann () absint ! com>
Date:       2014-02-18 19:07:08
Message-ID: 1695598202.986384.1392750428736.JavaMail.zimbra () absint ! com
[Download RAW message or body]

> On Tue, Jan 21, 2014 at 1:36 PM, Burkhard Lück <lueck@hube-lueck.de> wrote:
> > Yes, we discussed this issue already some months ago here:
> > http://lists.kde.org/?l=kde-doc-english&m=137512646306266&w=2
> >
> > Having the ktexteditor documentation in the code repo would solve
> > documentation problems with extragear applications (kile, krusader,
> > kdevelop?...), which can be build with different versions of kde, but as of
> > now
> > we have only a ktexteditor documentation for one version to provide.
> >
> > From my pov the split of the docbooks into ktexteditor + Kate + Kwrite
> > parts,
> > where the kate/kwrite docbooks just link to the ktexteditor docbook for the
> > relevant info, make much sense and solves the problems with extragear apps.
> 
> So I've been thinking about this and it occurs to me that most
> third-party (by that I mean not in kate.git, not necessarily not in
> KDE ;-) KatePart consumers present an interface very similar if not
> identical to KWrite itself, which makes sense since KWrite itself is
> just a simple interface to KatePart.  They have the same menus, an
> identical Settings > Configure Editor screen, etc.
> 
> If we were to move all the stuff out of kwrite's doc into a katepart
> doc, there would be pretty much nothing left.  So I think we should
> just move the kwrite doc over to ktexteditor.git, change most mentions
> of kwrite to be generic, and add some introductory text to the lead
> that says something like "Since KWrite is a simple wrapper around
> KatePart, this documentation applies equally to KWrite" for people who
> press F1 in KWrite and wonder why they're in the KatePart handbook.
> Make sense?
> 
> There are also some other issues I'm not sure how to deal with:
> 
> * In the past, we've tried to keep the KWrite documentation simple,
> thus we've kept documentation about advanced features of KatePart like
> regular expressions in the Kate handbook even though they're available
> in KWrite too.  This doesn't seem to work out as nicely when there's a
> shiny new KatePart handbook that people who are interested in advanced
> features like regular expressions (i.e. KDevelop users for sure ;-),
> so I guess we should move those kind of sections over to the new
> KatePart docbook?
> 
> * At the moment, the Kate handbook and KWrite handbook share several
> sections only exist as one .docbook file in git but that are sucked
> into both handbooks.  This way we can show e.g. the katepart
> configuration options as the whole configuration chapter for KWrite,
> and as one of two major sections in the Kate handbook.  But we won't
> be able to do this once the katepart doc is in a seperate git repo
> from the kate doc, at least not as things stand currently.
> 
> So assuming the KDocTools status quo, we'd have to replace these
> sections with links.  For some situations, that's okay, e.g. "click
> here to see all the options in the Editor Component tree shared with
> other programs that use KTextEditor" isn't too bad.  But we also share
> the basic editor chapter (part.docbook) and sending someone to another
> handbook for basic instructions on how to use the editor seems a
> little confusing to me.
> 
> Basically, I'm not sure if we can count on our average user to use the
> back button in KHelpCenter to get back to the documentation they
> started in, or if they'll just hit the Next button at the botttom of
> the section and end up in a menus chapter for katepart only that is
> missing half the menus in Kate and be very confused.
> 
> In practice, we've been doing something similar for the fundamentals
> documentation, but in that case I think it's more obvious that you're
> now in a handbook that is generic for all KDE applications and not
> specific to your current application.  For KatePart it's not nearly as
> obvious, the katepart documentation will look very similar to the kate
> documentation and it may not be immediately clear that you've been
> transported to a completely different handbook with completely
> different internal navigation.
> 
> Anyone else have any thoughts here?  Am I just not giving our users
> enough credit?  ;-)
> 
> If this does seem like a real problems to others, perhaps we should
> instead figure out a way to let the docbook inclusion thing work
> across modules.  (i already have an idea about how this might work
> that I can convert into a patch for review if the other docs folks are
> interested.)
> 
> This would benefit other KatePart users too, e.g. KDevelop's manual
> could just have a "Using the basic features of the editor" chapter
> that appears to be part of the KDevelop manual as far as users are
> concerned but is actually a completely seperate docbook in a seperate
> repo.  (I'm sure there are other docs where maintainers would be happy
> to have this ability too...)
I could live with either of both solutions: links or included docbook files,
I follow the decision of you documentation guys here, if you get one ;)

> 
> * What are we calling this thing nowadays anyway?  In the past,
> KTextEditor was the interface and KatePart the implementation, but now
> they are one and the same.  Is the "KatePart" name now dead and now we
> should call the whole thing "KTextEditor"?
I would stick with KatePart. But that is more personal taste (and we advertised it
like that since years ;)

Greetings
Christoph

-- 
----------------------------- Dr.-Ing. Christoph Cullmann ---------
AbsInt Angewandte Informatik GmbH      Email: cullmann@AbsInt.com
Science Park 1                         Tel:   +49-681-38360-22
66123 Saarbrücken                      Fax:   +49-681-38360-20
GERMANY                                WWW:   http://www.AbsInt.com
--------------------------------------------------------------------
Geschäftsführung: Dr.-Ing. Christian Ferdinand
Eingetragen im Handelsregister des Amtsgerichts Saarbrücken, HRB 11234
_______________________________________________
KWrite-Devel mailing list
KWrite-Devel@kde.org
https://mail.kde.org/mailman/listinfo/kwrite-devel

[prev in list] [next in list] [prev in thread] [next in thread] 