Re: Organization of gnome-user-docs, display in yelp



As Sasha points out, many of the documents that Aaron lists are chapters of
the User Guide. Before pregeneration was available, we had to split the
User Guide into individual chapters to reduce load time in Yelp. I
understand that with pregeneration implemented, load time is reduced
considerably and it is now a viable option to load an entire book, and not
just one of its component chapters.

I don't know how widely pregeneration is being used, but now might be a
good time to consider changing our approach and going with pregeneration
rather than the load-the-chapter option.

So this might result in a side pane in Yelp like this:

Introduction to GNOME
User Guide
System Admin Guide
.
.
. 
and so on 
.
.
.

But you could click on the books to show:

Introduction to GNOME
User Guide
|- Part 1 A Tour of the GNOME Desktop
|  |- Basic Skills
|  |- Overview
|  |- ... and so on ...
|- Part 2 Customizing Your GNOME Desktop
|  |- Basic Preferences
|  |- Advanced Preferences
|  |- ... and so on ...
|- Glossary
System Admin Guide
|- Using GConf
|- Customizing Menus
|- ... and so on ...
.
.
. 
and so on 
.
.
.

Implementing the pregeneration option would also enable us to have proper
links between chapters in a book. At present, the cross-references are just
text, not links. This is because in the present non-pregeneration system it
is not possible to link between chapter. Within a chapter is doable, but
not from one chapter to another.

If we are to go with the pregeneration option, then I would submit only one
OMF for the User Guide (currently there are approximately 15). As Sander
says, all of the help links to the User Guide would have to change.

FYI, to see the structure of the User Guide outside of Yelp, see
http://www.gnome.org/learn/users-guide/2.2.

In the structure illustrated above, I think there is room for both
documents, and there would not be confusion between the two.

What do people think?

Eugene

"Sander Vesik" <sander_traveling yahoo co uk> wrote:
>Date: Thu, 13 Feb 2003 21:03:55 +0000
>Aaron Weber wrote:
>> Hello all,
>> 
>> I've been looking at gnome-user-docs a little recently, and it's kind of 
>> got me confused, partly because I've had a hard time mapping files to 
>> the documents as displayed in Yelp.
>> 
>
>This is indeed a bit tricky - part of which comes from 'which files to look 
>at' and part from perfomance considerations. Its easier ones you notice the 
>presence of the xml files which name starts in 'w'.
>
>> It appears that we've got two general introductions-- both the 
>> gnome2-users-guide and the introduction-to-gnome. Do we need both of 
>> these? Could they be merged?
>> 
>> When I click "Desktop" I get the following documents list, which I 
>> assume is generated from OMF files:
>> 
>> Solaris Accessibility Guide
>> System Administration Guide
>> Introduction to GNOME
>> Accessibility Preferences
>> Basic Skills
>> Advanced Preferences
>> Basic Preferences
>> Menus
>> Desktop
>> Background
>> Sessions
>> Windows
>> Nautilus File Manager
>> Overview
>> Panels
>> Search for Files
>> 
>> I'm not even running Solaris!  Why is the "basic skills" section in the 
>> middle of the list? Should some of those items be listed under others?  
>> "Desktop Background" really sounds like it's about how to set your 
>> wallpaper, even though I know it's about how to use the desktop 
>> background-- could we call it "The Nautilus File Manager and the 
>> Desktop?" maybe. or "Files on the Desktop"?
>> 
>
>There isn't a linux specific accessibility guide yet. Sorting - the sorting 
>is presently in the order in which documents are registered in the 
>scrollkeeper database so everybody can (in principle) come up with their 
>own custom ordering.
>
>As for desktop - I think there have already been plenty of long threads on 
>it 8-)
>
>> Personally, I'd merge "Overview" and "introduction", put "basic skills" 
>> under that, then put all the preferences items under one heading, 
>> including the accessibility stuff.... but maybe not hide it:
>> 
>> Overview
>>   * Basic skills
>>   * Windows
>>   * The Nautilus file manager
>>   * Panels
>>   * Menus
>>   * Search for files
>> 
>> Preferences:
>>    * Basic Preferences
>>    * Advanced Preferences
>>    * Accessibility Preferences
>> 
>> and so forth.
>> 
>> That might be beyond what OMF will do, though. I dunno.
>> 
>
>This is indeed, not possible. But what we could do now that we have help 
>pre-generation is "unexpand" the user guide chapters and make it be 
>represented as one document again instead of having chapters accessible 
>individualy. This will however also mean changing a lot of help links, so 
>its probably something to be considered for 2.4
>
>> What do you all think about the way that module is organized? Is there a 
>> better way to do it?
>
>There are different, probably better, ways to present the information but 
>these don't really affect the module organisation for the most part.
>
>> 
>> a.
>
>__________________________________________________
>Do You Yahoo!?
>Everything you'll ever need on one web page
>from News and Sport to Email and Music Charts
>http://uk.my.yahoo.com
>_______________________________________________
>gnome-doc-list mailing list
>gnome-doc-list gnome org
>http://mail.gnome.org/mailman/listinfo/gnome-doc-list





[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]