Documentation has to be updated and extended

[tarsius]

Just wanted to say that I am aware that a lot of stuff still needs documentation and that I will add/update a lot of documentation before the release.

I will close all other issues that point out that one particular thing is undocumented. And put a link back here in each of the closed issues. So before I close this issue I can quickly have a look at each of the areas someone cared enough about to create a ticket, and can make sure they have all been addressed. But there is no point in having several tickets open.

---

Edit: Mentioning some things explicitly:

• add faq on how to improve performance, Performance regressions #1168
• new doc-strings for magit-section-{match,case,action} Refactor magit-section-{match,case,action} #1172
• new doc-strings for magit-with-section magit-insert-section and friends
• New Provide some sort of "commands that make sense at point" popup, smart actions annotations lisp help [?] #1332
• generate a pdf

[tarsius]

As I have mentioned in a comment on http://www.masteringemacs.org/articles/2013/12/06/introduction-magit-emacs-mode-git I am going to work on documentation now (and already have since I have announced that). But I won't do it all now, and instead focus on introductory things and fixing stuff that is simply not true any more.

[tarsius]

The functions that compose the process api now have proper doc-strings.

[tarsius]

Code has been rearranged somewhat (#1175). I consider doing so as part of improving the documentation (baby step toward "literate programming").

[stsquad]

I would appreciate some docs on how to correctly hook into a magit page. This kinda works but I have no idea why:

(defun my-magit-run-checkpatch ()
  "Run a checkpatch script against current commit."
  (interactive)
  (when (derived-mode-p 'magit-log-mode)
    (magit-section-action (item info "run checkpatch" t)
     ((commit)
       (message "doing commit check for %s" info)
       (my-magit--do-run-checkpatch info)))))

[tarsius]

@stsquad I am actually deprecating that function soon.

[stsquad]

@tarsius I hope there will be some mechanism to hook in functions like above to the various magit pages?

[tarsius]

@stsquad Yes, keymaps :-) Sections have a type which has to be specified when creating a section using magit-insert-section. That same macro also checks whether a variable magit-TYPE-section-map exists, and if so uses it as the (text property) keymap of the text making up the section. So all you have to do is add new bindings to the correct keymap. The type of a section can be determined using magit-describe-section and if the respective keymap variable does not exist yet you can just define it yourself.

While magit-section-action has been removed magit-section-case still exists (and it is properly documented (though the manual will have to discuss this in more detail)).

[mwfogleman]

According to #1645, we need a basic manual, an org-mode document. See that thread for the most basic requirements. We're aiming to export it to texinfo and HTML (pandoc?).

We need to start with a technical template that shows how to delimit symbols, include screenshots, exclude certain parts in one of the output formats, link to Git manpage resp. (?) web docs.

[mwfogleman]

I made a playground at:

https://github.com/mwfogleman/magit-next-manual

I have pandoc installed and running and was able to convert the HTML manual to (slightly messy) org.

I am of the opinion that it'd be a waste to lose that documentation, and would happy to help update it for the next branch.

[tarsius]

We're aiming to export it to texinfo and HTML (pandoc?).

I was thinking about org doing the export to texi and html. Pandoc could be acceptable, but I would rather avoid dependencies.

Here is an attempt to translate Org's own info documentation to org format: https://github.com/tsdye/orgmanual. Something along these lines I had in mind, but frankly that org file looks rather convolved so we would have to improve upon that.

Also if the costs are too high we can forgo exporting to texi/info. I do like the built-in info reader, but I don't consider it to be heresy if a big Emacs package does not provide the manual in the info format. Would still be nice and absolutely preferable, but not at all costs.

Anyway that really is something that can be decided on later.

What did you mean by a template? [from a private mail]

Now we can experiment with different approaches like you did, thanks for that. But we should not yet obfuscate the actual draft of the manual, with hacks that are required to export to certain output formats, which we might later decide not to support after all.

That being said it's still useful if we experiment now. I don't really feel like doing so right now, but if you feel like it, then that would be much appreciated. But be aware that you should get out something out of that work besides "it's going to help Magit", i.e. the learning/hacking should be useful/rewarding on it's own. Otherwise it would be a waste if we later decide to only provide the manual as an org file and a html export. Also see Worg the Org wiki, it's probably the finest wiki I have ever seen. We might end up doing something along these lines.

link to Git manpage resp. (?) web docs.

The Magit org file and the info page should link to the Git info page (or since that isn't installed by default the man pages). The exported webpage should link to the Git webpage because browsers are neither info nor manpage readers, they can however display webpages which are the result of exporting such resources to html :-)

I am of the opinion that it'd be a waste to lose that documentation, and would happy to help update it for the next branch.

There's one big problem: lawyers. I would like to include parts of the Git documentation which is released under GPL v2 and only v2. The current Magit manual uses the GFDL 1.2, which is not compatible.

Initially the parts taken from the Git docs will probably just small things like the descriptions of arguments. Later we might also include and adapt whole passages describing version control concepts.

So the plan is the start with a new org file with just the basic structure (not necessarily the final structure but one that is useful during the creation of the documentation). Add stubs for all the things that have to be documented, i.e. the commands and options. I should really do that soon, so that you and others can then start filling in the details. Meanwhile we can add all the missing doc-strings. Then we can copy the doc-strings and adjust them to better fit the format. Some improvements made in the manual can then flow back to the doc-strings.

But there's a problem. The source code is licensed under the GPLv3+ while the manual is licensed under the GPLv2-only. I can only see one feasible solution to that problem: everyone who contributes to documentation has to assign the copyright to me, so that I can freely move strings around. It's really quite annoying, but what can you do?

Which is also why I am throwing out the old manual. Probably we will restore some select portions later. To make that easier it would help if those who have made copyrightable contributions to the manual, could assign the copyright to me. But I don't intend to try to make everyone who ever contributed to the manual assign me the copyright.

was able to convert the HTML manual to (slightly messy) org.

That could proof to be useful later on but I would recommend you don't invest to much time into this right now. If we do include portions of the old manual then investigating who might be a copyright holder will likely (and sadly) be the most time consuming part of the process, and that will have to be done on the old history using the old format. Considering having to translate the syntax manually doesn't seem so horrible when taking this into account.

---

Meta. Wow that was long. I sometimes feel that if I did not reply in such detail and had instead invested that time into writing the manual, then it would be done by now. On the other hand, that's what I usually do for code. Here I often do the "efficient thing" and write it myself, instead of going through the more laborious process of reviewing and repeatably suggesting improvements after someone has dropped a badly integrated new feature. But as a result I end up writing 95% of the code and in the long run it would be more productive to get more people on board who have previously experienced that I e.g. prefer refactoring instead of working around the limitations of existing abstractions. So it's probably a good thing, if I try to do it differently for the data part.

[tarsius]

Guess what - by now that's a duplicate of the (more recent) #1645.