Expand the E2EE documentation

[telenieko]

Thanks to alphapapa & contributors for such an amazing Matrix client for Emacs. Combined with Beeper I now have all my social networks in one place: Emacs!

We now include as much information as possible about E2EE set up in a separate file (e2ee.org) in order to:

• Make up for the lack of documentation from Pantalaimon
• Have a place to include tips & tricks about making it work
• Have a place to direct users asking about E2EE in Ement.el (and suggesting them to submit updates/additions), like:
  • Connection fails with pantalaimon #54
  • Pantalaimon: "Encrypted by an unverified session" #60
  • Pantalaimon session verified, when run ement.el from emacsclient , it sends no cryptographic information to other device for session verification  matrix-org/pantalaimon#157
  • Sending messages with Pantalaimon seems to time out #33

Fixes #153

[telenieko]

@alphapapa I have very little knowledge about makem.sh and info pages. But I guess there's something more to be done to have the file included and the link from README work in info pages?

[alphapapa]

The readme is converted to an Info manual by the GNU ELPA build system. (One could also run it locally using ox-texinfo.)

To import one Org file into another when building the Info manual...I think it's possible, but I haven't done it yet myself, so we'll see.

All we need to focus on in this PR is the content. Integration into the rest of the docs can be handled later.

Thanks for contributing this!

[telenieko]

All we need to focus on in this PR is the content. Integration into the rest of the docs can be handled later.

Any feedback on that?

I think I can remove all the TODO entries and submit as is (it is fairly complete without the TODOs) and open a second PR to work on those which may take more time.

So: merge the current document (without TODO entries) now, leave the rest for another moment? Thoughts?

Thanks for contributing this!

you're welcome!

[alphapapa]

My first feedback on the content is that I'd like it to be oriented toward directing the user from start to finish, step-by-step. I think that numbered steps are helpful for telling the user how to proceed and exactly what to do. Looking at the document in its current state, imagining myself to be a user who's installed Ement but nothing else, it's not clear where to begin and what discrete steps to take.

Basically, I just need a user who's successfully installed and configured Pantalaimon to document the discrete, specific, exact steps they followed. Then I'll take care of context and integration.

[telenieko]

[... direct] the user from start to finish, step-by-step. I think that numbered steps are helpful for telling the user how to proceed and exactly what to do. Looking at the document in its current state, imagining myself to be a user who's installed Ement but nothing else, it's not clear where to begin and what discrete steps to take.

I think the new draft covers this a little better. There is now a clear indication of the steps to follow before going into the Hard part, which is client verification.

Let me know your thoughts!

[alphapapa]

@telenieko This seems like good progress. Thanks. Some next steps could be:

• Improve organization of the outline (e.g. Installation, Configuration, Usage, Troubleshooting/FAQ/Tips)
• Add a table of contents
• Make sure content flows sequentially (e.g. mentioning installation after instructions for running is out-of-order).
• Trim content (e.g. anything that could be made more concise or omitted probably should be). Especially, I'd prefer not to have instructions for building and installing Pantalaimon unless absolutely necessary.
• Collect any parts that could also be contributed upstream and consider doing that.

[phil-s]

This seemed like a noteworthy comment from krustyjonez in the chat channel, as the changes for this PR don't include the word dbus:

in addition, there are problems that are platform and distro specific
specifically - you must have dbus working + a GUI agent for dbus notifications
(which can also be a CLI - like Tiramisu - but you can't not have dbus + interactive alerting)

[telenieko]

This seemed like a noteworthy comment from krustyjonez in the chat channel, as the changes for this PR don't include the word dbus:

The current draft mentions the d-bus requirements in the "Requirements (for Pantalaimon)" section.

Note that it is spelled d-bus not dbus source.

you must have dbus working + a GUI agent for dbus notifications

Is that so? I know you must have a session bus, but is the GUI agent a requirement too? Would be good to know.

I have to refactor the current draft and bring some content directly to Pantalaimon, may take some days still! :(

Also, taking note of this gist for future reference.

[alphapapa]

#242 was recently sent, which appears to document some steps that this guide doesn't mention, like exporting and importing keys. Ideally we should consolidate these guides together.

Also, we should keep in mind that Ement is part of GNU ELPA, so in order for any of these contributions to be included directly, the submitters need to have signed the FSF Copyright Assignment for Emacs. @dionisos2 @telenieko Have you done this? (Apologies if I asked already.)

Thanks.

[dionisos2]

Hi @alphapapa, I didn’t sign the FSF (and didn’t know what it was before checking).

I think it is better if @telenieko take the information lacking in this document from the other one (so I don’t really need to sign anything), if he is ok with that.

[telenieko]

I'll merge in what's new from #242 and try to keep that around 15 lines, so @dionisos2 can skip the copyright assignment as per his last comment.

I'll go ahead and do mine, as I'm already above the (cumulative) 15 line limit.

TODO list (comes from above):

• Do FSF Copyright Assignment
• Improve organization of the outline (e.g. Installation, Configuration, Usage, Troubleshooting/FAQ/Tips)
• Add a table of contents
• Make sure content flows sequentially (e.g. mentioning installation after instructions for running is out-of-order).
• Trim content (e.g. anything that could be made more concise or omitted probably should be). Especially, not to have instructions for building and installing Pantalaimon unless absolutely necessary.
• Collect additional notes from Expand the E2EE documentation #232 and this gist

Also, if possible but not a blocker (because upstream does not appear to be very active):

• Collect any parts that could also be contributed upstream and consider doing that.

[telenieko]

I found this page from GNU that goes deeper into when the Copyright Assignment is needed or not. Leaving it here for reference as the issue came up.

[alphapapa]

@dionisos2 @telenieko I think that's fine as long as you use the ideas from @dionisos2 and explain them in your own words. Thank you!

[telenieko]

Just pinging here. Sorry this is still in my backlog; crazy month!

[alphapapa]

@telenieko Are you pinging me? If so, I guess the to-do list still needs to be done: #232 (comment) Or if you're asking someone else to take over, that's fine, just say so clearly, please.

[telenieko]

Hi, No, Just letting the world know I still plan to finish this!! 😊

Message ID: ***@***.***>

Sorry if that was not clear! Almost done with the FSF paperwork too.

[alphapapa]

No problem. Thank you. :)

[telenieko]

Just pushed a reviewed document, I think all feedback is in now.

Also sending now the FSF paperwork.

[alphapapa]

Just pushed a reviewed document, I think all feedback is in now.

Also sending now the FSF paperwork.

Thanks, this looks like a big improvement. I'll do some further editing myself, after you confirm the FSF CA is completed and I have time.

Meanwhile, we may want to direct new users here and get their feedback on the document.

[telenieko]

Also sending now the FSF paperwork.

@alphapapa, FSF CA is now complete.

[alphapapa]

Also sending now the FSF paperwork.

@alphapapa, FSF CA is now complete.

Thanks.

For future reference, here's another guide that was just posted on the Pantalaimon tracker: matrix-org/pantalaimon#154 (comment)