[PATCH] Updated the user-manual

[Reinout Hoornweg]

On 2013-02-19 12:29, Cristian Ionescu-Idbohrn wrote:
> On Mon, 18 Feb 2013, Reinout Hoornweg wrote:
>> 
>> Added headers, borders, etc. to the tables in "Viewing and completing
>> your logs".
> 
> May fill some purpose, but I don't really enjoy that much reading
> "enhanced" simple text.  Call me "old fasioned", if you want to.
> 
> But, please, let's keep things neat, shan't we?
> Worry about whitespace in pure text too.
> Proper tabification may improve the "user experience" (tm), at least 
> for
> some grumpy users like me :)

The tables were in the original text, they're not new.
All I did was remove some of the header options (mainly used for html) 
and unused cell-markers, trying to make things more neat. :-)

> But just ignore me if you feel so.

No need to be grumpy. I agree with you text should be user-readable as 
much as possible. Fortunately asciidoc renders to text.
"make user-manual.text" (using the makefile in the Documentation 
directory) makes a pure text-file with reasonably consistent formatting.

> And that brings me to some questions.  There are a few things about 
> the
> consistency of the text, like:
> 
> * what should the fill-column be (right margin in emacs talk, you 
> know)
> * should the text be justified (emacs talk, again)?
> * is tabification desirable?
> * would sentence ending fullstop be followed by two spaces or just 
> one?
> 
> What I mean is, it might be desirable to try to make both worlds 
> happy.
> We do strive for world domination, after all, don't we ;)
> Even at the documentation level?

Before I helped with the documentation, the format was already 
asciidoc. Perhaps because the documentation was initially intended for 
the website? I don't know.
But the advantage of using something like asciidoc is that we can 
create both text and html from the same source.

One thing to keep in mind: It will be more difficult to have complete 
information in text-format when using screenshots. Subsurface is a 
graphical application so I think it is unavoidable images will find 
their way into the manual.

Reinout