[PATCH] Updated the user-manual

[Dirk Hohndel]

On Feb 19, 2013, at 5:28 AM, Cristian Ionescu-Idbohrn wrote:

> On Tue, 19 Feb 2013, Reinout Hoornweg wrote:
>> 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.
> 
> Sorry, it was not meant as criticism, more as a wish.  I shouldn't have
> replied to your message but write a new one, I realize that now.

Definitely. Especially a message whining about things not being the way
you want them to be, with [PATCH] in the subject but no patch attached.

>> 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.
> 
> Right.  Nice for a doc-package.  But I read the source and notice some
> stuff that might need some cleanup.  Didn't bother generating manuals.

Well, if you want things cleaned up, send patches.

>>> 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.
> 
> Yes, I agree.  I'm fine with asciidoc for presentation.  I was refering to
> the source.  My expectation is it should fit nicely in an 80-column wide
> terminal.

That's utter bullshit. No one uses 80 column terminal windows or editor windows.
Artificially forcing people to do that causes them to use short, non-descriptive 
variable and function names and causes ridiculous line wrapping that makes
the code harder to read and maintain.

So no, absolutely not.

If you want easy to read (in text mode) docs, run make user_manual.text
If you don't like the output of that, send reasonable patches that fix that.
Our target audience are divers - for them I need a web site and possibly
a nice printable PDF document. The <0.1% of divers that prefer a plain
ascii text file with proper tabification and consistent right margins…
I'm sure they are gurus enough to make that happen by themselves.

/D
-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 4130 bytes
Desc: not available
URL: <http://lists.hohndel.org/pipermail/subsurface/attachments/20130219/90d865e9/attachment.bin>