HI Jan - No worries, I'm happy to fix any of this stuff, and the license issue: I just chose one at random, figuring you'd let me know which license you prefer. I'll get that fixed and touch up some of the rest of it using these comments. Then I'll send around a second version before submitting.
We'll have to collaborate on getting this into the system, I guess. Seems we just make a top level "doc" folder in the Git repository, and then the KDE scripts (assuming now that you're a KDE project you're moving the code over to their repository?) knows what to do and the translators get involved. Getting the help file to open and show this (rendered) text is another issue; there's apparently some specific trigger code that needs to get worked into the app's help menu. I'll see what I can find out. I'll see if I can get v2 of the docs wrapped up by early next week. Happy weekend to everyone - Randy On Feb 1, 2013, at 4:33 PM, Jan Kundrát wrote: > On Tuesday, 29 January 2013 22:18:40 CEST, Randall Wood wrote: >> Team - here's a first draft of the docs (attached, hopefully the mailing >> list server sends along the attachment; otherwise I'll paste and resend). >> >> I'm asking the folks on the kde-docs-english mailing list for some initial >> criticism; in particular some of the XML might be funky. When I get it I'll >> probably have a second version of this doc. Have a look too and see if >> you'd like any changes to the text - it's certainly still a work in progress. > > Hi Randy, > thanks a lot for taking the time to write this and sorry for not responding > earlier. I hope I haven't managed to put you off yet. > > I've read the XML source (can you get the rendered version somewhere next > time, please?) and am pretty impressed -- it documents the GUI and feels just > right in general. > > I have a problem with the licensing, though. The file references the > "FDLNotice", I'll assume it's the GNU FDL license. The disadvantage of this > is that this license is *not* compatible with the GPL which means that one > cannot move the documentation between the C++ sources and the docs. Could you > please make the license available under GPLv2+ (or actually the > GPLv2/GPLv3/next-if-KDEeV-approves combination) and a recent version of the > CC-BY-SA as well? > > I also have no idea how KDE's documentation process works (and no intention > to get myself involved in there). This means that I cannot offer any help > with the "proper procedures" etc, but from your remark about being in touch > with the KDE's docs team it looks like you're fien with it. I just want you > to know that you'll be on your own here, I don't even know how to make sure > that the guide gets available from some KDE's website etc. > > There are a couple of factual inaccuracies: > > - The remark about "same GUI on desktop and phone" is a bit misleading, what > is shared is the actual backend code, the GUIs are completely separate. > > - I definitely agree with recommending fastmail.fm, it's the best freely > available service I'm aware of. That part shall probably mention that some of > the IMAP server software suck so much that the effective performance would be > on par with just using POP3 (Courier), close to it (Exchange) or just much > something to be desired (GMail). > > - Trojita doesn't support multiple accounts just yet. The docs shall probably > not conflate the notion of an "identity" (the human name visible as the > sender of the e-mail and related settings) and "account" (the physical place > to which Trojita connects and which stores the e-mails). For example, right > now I have four mail identities, but just a single IMAP account. > > - "Local process" does *not* work over network; it's something usable for > users who know what they're doing (like when they have SSH agent working, > they might want to use something like `ssh imap.example.org dovecot > --exec-mail imap` in there). "SSL" is for connecting over encrypted protocol > (and to a special port) form the very beginning while "TCP" is for > connections which are transparently upgraded to TLS encryption via the > STARTTLS command. > > - Password prompts actually happen just once per session, i.e. they are held > in memory until the app exits. > > - The "blacklist capabilities" is a workaround for broken or buggy servers. > I'm strongly voting for a formulation like "If you're aware of some features > that your provider advertizes but actually doesn't support,...". > > - The part which deletes old data from cache is not implemented yet. > > - The "path to IMAP server binary" and "path to sendmail" are only used (and > available) when the user has selected the "local process" connection method > for the corresponding service. > > - BURL has not been a draft since 2006, but the rest of that sentence is 100% > correct. Just don't call it a draft, please. > > - Other layouts of the app are possible, see View->Layout->Wide. > > - There's also a "reply to list" if the message you're replying to arrived > via a mailing list software which is properly configured to mark it as such. > > - About the missing shortcuts for replying -- this is a recent regression. > The reason is that Trojita tries to always offer the most reasonable way of > replying as the first option in the menu (so that if a message arrived via a > ML, the "reply to list" is the default option, otherwise it's the "private > reply" etc). I'm not sure which shortcuts to assign to which action and also > cannot decide whether there shall also be a "generic reply shortcut" which > would just select the default mode of replying. Opinions and suggestions > welcome. > > - The part about composing could probably mention the message drafts (the > expander arrow for this button in the post-0.3.91 git versions). > > - Expunge works just on the current mailbox, dleeted messages in other > mailboxes are ignored. > > - Offline mode doesn't affect the message ocmposer in any way (that might be > considered a bug). What it does is preventing the mail *reader* form fetching > any new data, so that you'll only have access to mailboxes and messages which > are in the trojita's cache. > > - The "free access" is not inefficient, but just enables more aggressive > preloading of data which the user has not requested to be loaded yet. It's a > speculation which will cut latency if the guess was succesfull, but might > transfer more data. (i.e. the "expensive" mode will only load headers for > messages which are currently visible, but "free access" will assume that the > next and previous hundred or so messages might come into view soon and hence > it makes sense to make sure their headers are ready as well). > > - It shall probably be noted that threading and sorting depends on the server > supporting voluntary IMAP extensions. Trojita cannot do that on the client > side because it would require downloading headers of all messages in a > mailbox. > > - The sorting and threading (and searching in absence of CONTEXT=SEARCH, i.e. > on other IMAP servers than Dovecot) will consume nontrivial amounts of data > when new messages arrive into the mailbox. This is, in general, true for more > features (the "show only subscribed" currently requires an extension as well). > > - The copyright for me is 2006 - 2013, not 2010-2012. I recall fixing that > recently in the about dialog, sorry for confusion. > > - There are other contributors, see the LICENSE file. > > - Qt shall be spellt out like this, not as "QT". > > Some of them are serious, some just nitpicking -- I make one pass through the > text and am now reporting what I don't agree with, no matter how relevant it > is to the user's docs. > > Thanks again for your work, it's appreciated. > > With kind regards, > Jan > > -- > Trojitá, a fast Qt IMAP e-mail client -- http://trojita.flaska.net/ >
