[PATCH] Updated the user-manual

Cristian Ionescu-Idbohrn cristian.ionescu-idbohrn at axis.com
Tue Feb 19 05:28:01 PST 2013


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.

> 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.

> > 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.


Cheers,

-- 
Cristian


More information about the subsurface mailing list