Update the User Manual for 0.4

[vansia43]

This PR addresses updating the user manual as identified in #243 .

Some highlights to note:

• Most old, outdated pages and images deleted in commit 05178af.
• I left the sync services related pages (gtg-add-sync.page and gtg-create-sync.page) in the folder in case sync services come back. I also left gtg-create-plugin.page in the folder but did not include it in the user documentation as I did not think it really belonged in here but wasn't sure if it needed to be added somewhere else.
• I also kept the videos in in the videos folder. I didn't have time to redo these but I thought that the documentation was fine without these for now.
• All new graphics and application of appropriate Mallard styles for readability.
• Fixed broken Mallard attributes on some pages that were referencing a deprecated experimental namespace.
• Many of the pages were condensed and the index.page was reorganized.
• Developer topics such as Installing the Daily PPA and the Credits were removed. An individual Developer Resources topic page was created with links to the appropriate pages in this repo for anything contributor-related.
• I ended up leaving in the FAQ (for now). This includes the one FAQ question here: https://wiki.gnome.org/Apps/GTG/FAQ where I just point the user to Github.
• Everything from here is now in the docs: https://wiki.gnome.org/Apps/GTG/documentation.
• Updated gtg-tag-color.page to include requested note about color squares/icons.
• Updated search pages to highlight GTG's natural language parsing ability and give a lot more examples for searches.
• I added myself to the DOCUMENTERS in info.py

[leio]

There should now be updates done to docs/user_manual/meson.build as well, as the initial meson port was merged. Any new pages that should be installed should be added to the sources array; anything that was removed or shouldn't be installed anymore should be removed. Same for figures and other media, but in the media array instead of sources.
As we worked on this in parallel, I can do this as well, but I'm not sure which files you thing shouldn't be installed anymore, per your notes (I see 3 mentioned in your bullet points; unsure about one of them, and maybe there's more?)

[vansia43]

Hi @leio. I was listing some highlights in the bullets but a number of pages were deleted/updated/combined. I also kept 1 or 2 pages related to sync services in the user manual folder that are not relevant at this moment but could be used in the future. Those items probably shouldn't be added to the build but can remain in the user_manaul folder. It was more in case we needed to add them back into the manual. The deletions were within one of the commits I highlighted but that can be tedious to parse through so I can make the updates to that file, easy enough. Should I add it to this PR so all of this is updated at the same time?

Another thing to note, the meson.build piece is a bit over my level but I understand what needs to be done and have no problem updating the file. I think that if this is something that needs to be updated in tandem with any documentation changes to new or deleted files (for example, with a new feature, a new image is added to a page), that should be noted somewhere. While I plan to stay on board and making updates for this project for the foreseeable future, I was thinking about creating some contributor documentation, for updating the user docs. A non-dev contributor may not realize that these pieces need to be updated as well.

[leio]

Ideally I think that it would be good if the commit adding or removing a file does the appropriate meson.build updates as well (e.g. commit that removes some pages would include the removal of them in meson.build as well; and additions of pages updates would hook them up in meson in the same commit too).

I think the meson bits shouldn't matter beyond just having the list of pages and media up to date, as you can still open it raw with yelp and see it immediately, etc. The benefits come from the installation and translation handling - figures without "translations" will get automatically symlinked and pages are created from PO files that can be managed through standard means across changes to English (C) version.

[nekohayo]

I have no issue with the changes in this merge request. I'll admit I've read in a bunch of directions at once and so haven't read "every single word" with extreme attention, but overall it looks great to me.

I have a bunch of ideas/suggestions but I threw those into #243 (comment) (and technically this could even be spun into its own ticket, if seen as too intrusive).

[vansia43]

@nekohayo , as I mentioned in #243 , I am happy to continue making updates to these docs. Just let me know if I should be opening separate issues or continue everything in #243. We will call this one the MVP 0.4 user docs and I will keep improving the docs based on your suggestions (as well as a few that I have noted to myself) in separate requests. It will help to have this request merged so that I can start working in smaller chunks on additional updates without having a long commit history (I have not mastered the interactive rebase yet ;) ). I updated the meson.build file and deleted one remaining, outdated .png file that I had missed. Please note, as I mentioned previously, that there were a few files that are not included in the meson.build file but are still in the /user_manual/C folder:

Pages:
gtg-add-sync.page
gtg-create-plugin.page
gtg-create-sync.page
gtg-sync.page

Images:
Select_sync_service.png
Select-sync.png

These pages/images could be eventually updated and again viable. I didn't think they should be deleted but they are not a part of the build and none of the other .pages refer or link to them.

The two videos:
Getstarted.ogg
Quick-add2.webm

These are definitely outdated, but I want to be able to use them as a stretch goal to re-create or do something similar in the future. I know some people learn better with videos. So, if we think that these are still good to have, I can remake at some point in the future.

Let me know if there is an issue in keeping anything in the folder that is not in the build. Otherwise, this is good to merge. Thanks again!

[nekohayo]

OK there's one last thing that kinda theoretically bugs me and I (unfortunately) hadn't realized before: the commit messages don't follow convention (see https://chris.beams.io/posts/git-commit/, but specifically the part about having a short "subject line", at https://chris.beams.io/posts/git-commit/#limit-50 ) and are therefore not easy to read or to figure out what a particular commit is "essentially about".

Currently, the commits's descriptive messages have everything on one single line, and those were of course meant to be a list of things that were changed since I see they were separated by semicolons. Now, I can easily fix/rewrite the messages of your commits to split them across multiple lines, the only problem is that I would still need to have some sort of short descriptive "subject" line for each of them, and I find myself at a loss as to what it could be, and I don't want to denature your work either. @vansia43 would you have an idea of some summary short "subject" for each of those commits that I could put there for you? If you give me such a list (in the order of the commits) then I can pretty easily apply that fix for you.

If that's too much work / too annoying to solve post-facto and you don't feel inspired, we can ignore that problem and I can merge as-is, but I do think it is worth having otherwise (especially in the future) because it makes it much clearer for the casual onlooker. If you haven't tried it yet, I can say that the "gitg" app helps a lot with the commit message line lengths, for future commits :)

[vansia43]

@nekohayo Hopefully these are good enough titles. Going further these will be a lot shorter. Let me know if you have any issues with these. Thanks!

b433882
Restructure index and remove outdated pages

db60454
Edits for style, clarity, and attribute fixes

21e00cb
Edit main task pages

24a05f2
Edit search-related pages

41774ed
Edit style on all pages

05178af
Delete outdated files and images

0dc8f69
Add FAQ and Translation pages

223c2d1
Seemed fine as is

cec2760
This was a merge commit - feel free to squash in doing the rebase

b4fd4eb
Update meson.build

[nekohayo]

Thank you for this Danielle, I have now taken your proposed titles, adjusted them a little bit (I took some liberties with the extended descriptions too) for length purposes and to explicitly mention "user manual" whenever possible, because as I rebased and pushed your commits, they will appear as fast-forward (i.e. a "straight line of commits").

I considered the fact that some commits renamed/moved files and then deleted them, ideally I would have liked to be able to "cancel out" those changes by squashing them, but since they were tied to other changes I couldn't do that without messing with the history in a significant way.

Anyhow. All the changes have now been merged to master. You can now delete or reset your userdocs branch to match the current state of master. To do so, assuming you have no uncommited file changes in your folder:

git remote update  # but will this update from our origin remote? hmm...
git checkout master  # this switches you to your local "master" branch
git reset --hard origin/master  # the big question here is, is your "origin" remote actually our origin, https://github.com/getting-things-gnome/gtg.git ?
git checkout userdocs  # this switches you back to your local "userdocs" branch
git reset --hard master  # reset "userdocs" to the same state as your local "master" branch

Normally it should work, I think... the only tricky point is the "origin" remote question, that I'm not sure you have set up in the same way as me. If you are unsure or are encountering trouble, feel free to poke me on IRC and we can even do a desktop screensharing session to get you back up to speed quickly.