Re: Gnome-App Template Proposed Updates

[Eliot Landrum <eliot landrum cx>]

On Fri, Jul 07, 2000 at 02:11:41PM +0200, Alexander Kirillov wrote:
> 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>. 

I've been searching around and I can't find any reason why I was stuck so firmly with <section>. Since I can't come up with anything, there's no reason to change.

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

I don't see how it is overkill. It is simply logical and easy to understand. Would you rather go with a numbering scheme? That loses the flexibility of DocBook.

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

Sure, that's fine to leave it to the author. I'm just submitting my scheme as one for reference. Perhaps someone else out there doesn't think it is overkill and would like to use it. It's been extremely useful for me in several major documents because I didn't have to think about ID colisions at all. Each section clearly had an existing ID that was perfectly logical.

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

Perhaps not. These documents are dull though.. I like to liven them up a bit.

> As for "you", I'd like to keep it - but then again, this is up to the author
> to decide.

Perhaps, but as any good English teacher will know, using "you" can easily get authors in trouble. Once one gets in the habit of using "you," it is very simple to forget who "you" is and begin to mix up who "you" is. Sometimes "you" may be the network/system administrator, the user, the receiver of a document, etc. It's just easier to say who "you" is as a habit than to fall into a identification trap. :)

-- 
Eliot Landrum
eliot@landrum.cx
GnuPG ID: 8F5B499E

-Soli Deo Gloria-

PGP signature