Re: PLEASE, PLEASE produce user-doc IN ONE HUMONGOUS FILE. Way it is now is basically IMPOSSIBLE to traverse.

[Shaun McCance <shaunm gnome org>]

On Thu, 2009-09-03 at 12:49 -0400, David Combs wrote:
> Subject:  PLEASE, PLEASE produce user-doc IN ONE HUMONGOUS FILE.  Way
> it is now is basically IMPOSSIBLE to traverse.
>  
> The way it seems to be now is that each subject, even each
> SUB-subject, is on a SEPARATE PAGE (site).
>  
> Which makes it plain impossibly difficult, and also an awful pain –
> clearly whoever was in charge of the project NEVER HAD TO USE THE
> THING HIM/HERSELF – that person clearly already knew gnome.

Hi David,

I'm sorry the documentation isn't meeting your expectations.
Many users prefer information to be divided into digestible
chunks so they can find the information they're looking for
quickly.  People get lost in one humongous file.

It's certainly true that those of use responsible for making
and formatting the documentation are generally not in our
target readership.  That's true of any documentation effort.
Anybody with the expertise to provide documentation is, by
definition, not somebody who needs it.  But we have had to
use documentation for other products, and we try to pay
attention to what works and what doesn't, both for ourselves
and for other users that we have the opportunity to observe.

Clearly your habits, experiences, and expectations are outside
of what we have designed for.  I'd be interested in learning
more about your work habits and how you use the documentation
so that we can better help users like you in the future.

> Myself, I’m coming from YEARS (decades?) using CDE on Solaris, and now
> Solaris 10 is demanding, basically, that we use Gnome.

>  
> You know, best of all would be html, so we could run it thru LYNX (not
> links, but the cat-type animal, LYNX) and get a, admittedly
> pictureless and tableless, nicely-formatted ascii result – something
> we can GREP through! 

The documentation you're referring to is written in DocBook,
which effectively puts everything in one linear document.
(Sometimes we split things into multiple files using common
XML inclusions mechanisms, but there are standard tools to
deal with this.)

You can create a one-page HTML file with the following command:

gnome-doc-tool -d 0 /usr/share/gnome/help/user-guide/C/user-guide.xml

Note that this will create a figures subdirectory to hold the
images referenced from the document, so you might want to run
this in a new directory.

Note also that this assumes Gnome is installed in /usr/share.
I don't have access to a Solaris machine.  I don't know if
Solaris installs Gnome elsewhere.  Some systems install it
somewhere under /opt.

I hope this has been at least somewhat helpful.

--
Shaun