[haiku] Re: Man

On Mon, Aug 30, 2010 at 11:06:36PM -0400, Justin Stressman wrote:
> I just wanted to chime in and say that just earlier today I was reading
> through the user guide
> http://www.haiku-os.org/docs/userguide/en/gui.html
> 
> And I noted to myself how much I loved the clean and beautiful design that
> fit the Haiku aesthetic so well.

I'll dip my oar in one more time, too.  I agree totally that maintaining
the 'cleanliness' that the system currently has is vital.
> 
> 
> The first thing I fell in love with in Haiku was the simplicity and the
> aesthetic. It was clean, simple, elegant. And now with Web+ it has a browser
> that is equally clean, quick, elegant, etc.

Its quickness is important.  Good old NetPositive was ideal for HTML docs
because they pop up immediately.  Trying to use something like Firefox
as a standardized doc reader would be irritating as hell.

> 
> So I guess in the end my vote (based on the discussion so far) comes down to
> "--help should provide what you need for simple command usage. Anything more
> complex should be referred to the proper html styled help that looks like
> the current Haiku User Guide." That way you don't end up having to support
> multiple formats for help files, and both quick usage reference and complex
> usage reference are both handled appropriately to the level of
> responsiveness and detail needed for each.

My own feeling is that there are (at least?) three useful levels of
information.  A '--help' option should just display a list of all
arguments in as small a space as possible.  If feasible (and it often
isn't!) it should fit onto a single screen.

If you need more info about an option, you go to the 'man page', in
whatever convenient form it exists.  Again, this should be brief,
but complete.  In the old unix days, I'd have a loose-leaf manual full of
these, and most of them *were* just single pages, because of the philosophy
of simple single-purpose commands.  Not always the case with today's
Swiss army knife commands...

If you really want to go deep, you refer to a full manual.  The obvious
format for this is HTML, where you can follow links to explore a topic,
though I think it can still be pretty basic -- no Javascript needed.

The man page level is a bit more questionable.  I did a bit more research
since I called the man command 'lightweight'.  I'd forgotten it requires
some kind of roff to actually do the formatting, and that could add a
couple of megabytes to the overhead.  OTOH man pages are pretty much
just text, so HTML seems a bit of overkill for display in a Terminal,
where you'd need a text-based browser.

So how about StyledEdit text?  If you display it in StyledEdit itself,
you get all the font-sizing, bolding and so on. If you 'more' it in
a Terminal, you get unembellished text, but I suspect it wouldn't be
hard to write a utility that supplied the bold and underlined text
that you get from the usual ***x man command.

Existing old-style man pages would need some tool to 'StyledEdit' them,
but agin that seems doable.  What do you think?

Cheers,
        -- Pete --



Other related posts: