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/
