Help needed: authors for user manual

[Willem Ferguson]

Thank you for your offer of help with the subsurface documentation.

The manual is written in asciidoc format and is normally found in the
Documentation folder of your subsurface installation.

If you do not have asciidoc, you need to download it. You turn the
asciidoc file into an HTML format file with the command:

asciidoc -a toc -a toclevels=3 user-manual.txt

Or you can simply say "make" in the Documentation directory and have it
built automagically. The toc may not be the same, though.

N.B.: user-manual.txt is the definitive source file.

N.B.: user-manual.html is merely the same file, viewable in a bit more
friendly way as HTML. Check the HTML file to read the content more
easily and to see how asciidoc has interpreted your additions. Do NOT
edit the HTML file since this will not be reflected in the further
editing process. Editing should be performed on user-manual.txt.

At the end of the manual, several crucial parts of documentation are
listed that need to be worked on. It would be useful
to, if you became involved with updating the manual, to define the
sections you are involved in by sending mail to this list. This will
help to eliminate unnecessary duplication. On the other hand, if there
are other (unlisted) aspects of the manual you would like to work on,
feel absolutely free to do so.
  
The easiest way to perform updates is by using git. After making changes and adding images you need to do these steps:

git add Documentation/user-manual.txt

(if you added imagefor each image that you added)
git add Documentation/images/xxx.png
git commit -s -a
(then an editor opens up that lets you add a commit message - please
describe briefly what you changed)

the easiest way to send in your changes is this:

git log
look for the first commit that isn't yours
each commit has a looong hex number after the word "commit" (it's called
it's hash or SHA). Copy that SHA (of the first commit prior to your
commits) and then call

git format-patch <copy the SHA>

Or, if you did only one commit (or you know you did, say, 3 commits) you
can also do

git format-patch HEAD~1

git format-patch HEAD~3

This creates files that are numbered and have the commit titles as their
names

0001-Add-better-description-of-preferences.patch

attach these files to an email and send them to the Subsurface mailing
list

Kind regards,
Willemf