Re:Gnome-App Template Proposed Updates

[Alexander Kirillov <kirillov math sunysb edu>]

On Thu, 6 Jul 2000, Eliot Landrum wrote:

> 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 strongly object against this. There is a reason for having sections
of different levels, and having <sect1>, <sect2>, etc, really helps
keeping track of this. And we do not need to nest them infinitely: I
have not yet seen a situation which couldn't be handled using <sect1>,
<sect2>, <sect3>. 



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

Yes, each section must have an id, and we have to be careful that id's
are distinct, but I think that your scheme is an overkill. Formalizing
it like this makes it much more difficult for authors to follow these
rules - for example, I'd hate to rewrite panel manual using this
scheme. And for most docs, it is easy to ensure that all id's are
unique without such a scheme - if not, db2html will complain. I'd
leave it to the author. 

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

I do not think it is really necessary to have shots of menus. As for
"you", I'd like to keep it - but then again, this is up to the author
to decide.

Sasha