Re: Gnome-App Template Proposed Updates

[Dan Mueth <d-mueth uchicago edu>]

On Thu, 6 Jul 2000, Eliot Landrum wrote:

> Hello All!
> 
> There were a couple of things bugging me about the gnome-app-template,
> so, in typical open source fashion, I modified it.
> 
> I've put my changes up at:
> 
> 	http://eliot.landrum.cx/gdp/gnome-app-template/html/
> 	http://eliot.landrum.cx/gdp/gnome-app-template/gnome-app-template.sgml
> 
> Here's the major changes that I made, changes 1-6 are "meta" changes
> and the rest are specific changes:
> 
> 1. Starting at the top, entities - I created two new entities and
> changed the name of the existing one. I get tired of typing
> "<application>MY-GNOME-APP</application>" so the first new one is
> <!ENTITY app "<application>MY-GNOME-APP</application>">. It's so much
> easier to type &app;. Secondly, I added &manver; because I always
> forget to change the manual version midway down the document. I
> changed &version; to &appver; to match the naming convention of
> &manver;.

[looking ahead - I see Karl just discussed this]

> 2. I changed all sect1, sect2 and sect3's to section. For some reason
> I like <section> better... Mostly because they can be nested to
> infinity. It seems like I read that numbered sect's were going to be
> removed at some point, but now I can't find anything to back that up.
> Anyone know anything about this?

I vaguely recall somebody suggesting this long ago and that there was a
reason we kept <sect1>, <sect2>, ...  Looking through the gnome-doc-list
archives, it seems like the main arguments against it was (dcm) that it
made creation of a table of contents difficult and prevented the
stylesheet from handling different sectioning levels differently.  If
there is any reason why this is no longer a problem, then we can consider
changing.  Since Dave seems to be the only one who understands the black
magic of writing stylesheets, we should check this with him before making
the change.  Dave?

> 3. Section id's - I described this in the comments, but all sections
> and figures should have an id. To avoid id collitions, I've created a
> simple naming convention. A section is simply:
> 
> 	section[-subsection][-subsubsection][...]
> 
> All figures are prefixed by figure- and have the same name as the
> section. If there are more than one images (like in the usage-menubar
> section of the template), then each figure has a new "subsection"
> name. For instance, figure-usage-menubar-file,
> figure-usage-menubar-edit, etc. The filename follows these names too..
> just without the figure-. So I've got usage-menubar-file.png and
> usage-menubar-edit.png.

If we omitted id's, then we should add them.  While it would be
nice to have an organized id naming system like this, we have to be very
careful the id names don't get too long; They are limited to about 40
characters in length.  Will this be a problem?  

> 4. All comments to note sections are now in the format:
> 
> 	<!-- BEGIN: SECTION -->
> 	
> 	<!-- BEGIN: SECTION-SUBSECTION -->
> 
> 	<!-- END: SECTION-SUBSECTION -->
> 
> 	<!-- END: SECTION -->
> 
> All of those ==='s gave me headache. None of them were of the same
> length either..

I found them helpful, but this is merely a matter of taste.  We should do
whatever most people prefer.

> 5. I changed the legalnotice to have the FSF's address be formatted
> the same as the license section (see lines 79-84).

This is how we originally did them.  However the output from db2html does
not format <address>'s in the <legalnotice> right.  Instead of formatting
it as a real address, or even as an inline address (what you get the old
way, leaving out <address>), it tries to do an inline address on a new
line.  If you can identify the cause of this problem and fix it, that
would be great.  Otherwise, we probably should keep the <address> out of
the <legalnotice> since it is broken:(

> 6. Created a glade MY-GNOME-APP and took appropriate screenshots of
> the glade file. If someone can get it to build, we can include better
> shots without the black glade borders. My glade segfaults when I hit
> "build."

You could send me the Glade XML file and I can try to build it.

> 7. Added a usage-toolbar section talking about toolbar functions.

Looks good.

> 8. Added screenshots of each menu in the usage-menubar section. Also
> removed references to "you" in the menu item descriptions.

I'd be curious to hear other people's opinions of this.  I think the use
of "you" was intentional.  I think the screenshots may be overkill.  In
fact, as discussed in an earlier thread, these detailed descriptions of
the UI are painful and uninteresting to the reader and will soon be
obsoleted when the pop-up help is finished.

> 9. I completely overhauled the prefs section.

Do people feel we should have screenshots for each tab?  I used to feel we
should, but now I am not so sure since this can quickly become a burden
since some apps have many tabs.  I'm inclined to say we only show one tab
unless there is something non-trivial in a tab which requires a
screenshot.  As above, when we start implementing our new style (thanks
Aaron), the emphasis will be more on how to use the application and less
on detailing the UI, so this may not be so much of an issue.

> That's about it... Feel free to discuss any of these changes. Most of
> these are personal use choices, but I thought maybe the template would
> benefit from some of them.

Thanks for the work.  Hopefully we can use some of these.

Dan