Re: Gnome-App Template Proposed Updates

[Eliot Landrum <eliot landrum cx>]

On Fri, Jul 07, 2000 at 05:15:22AM +0200, Karl Eichwalder wrote:
> Eliot Landrum <eliot@landrum.cx> writes:
> 
> > 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;.
> 
> Too short (in the long run) and too "meta".  If all docs will use &app;
> it isn't possible to concatenate all the separate docs into one document
> tree (grove): the first app entity wins.  Better use:
> 
>     <!ENTITY MY-GNOME-APP "<application>MY-GNOME-APP</application>">
> 
> =>
> 
>     <!ENTITY app-gnumeric "<application>gnumeric</application>">

I hadn't thought of having to put multiple docs into one. Never had that pleasure... probably the app-gnumeric example would be the easiest, but might cause entity collisions.

> > 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;.
> 
> Using those version "macros" is dangerous.  Increasing the version
> number automatically without checking the contents will make the text
> unreliable.  I'd vote to add processing instruction and to match the PI
> against the following &ver; number.

These are no "macros" -- I would never update the version automatically without checking. Since I usually ignore the entire <artheader> section when updating and the manual version is lodged right at the end of the this section. Placing the version at the top in an ENTITY reminds me to change it instead of ignoring that one little line at the end of <artheader>.

> > 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.
> 
> Nice idea but in practice it doesn't work -- authors are famous for
> moving around pictures and sections ;)

I disagree. It works perfectly in practice. I've used it in numerous documents with no difficulties. Having the filenames match sections allows you to quickly find the file that needs changing because it matches an exisiting scheme.

> I like RefTeX's (reftex.el)
> approach most: just use a prefix and a number for all labels.  What's
> needed is a ID server where writers can "acquire" IDs.

This violates the entire idea of DocBook -- dynamic content. I'd hate to get stuck with all my figure id's being numbered 1-5 and then I stick a new one in at place 4 which shifts old 4 and 5 to 5 and 6. Having names that match content and sections allows modification/additions to the figures/sections with no problems.


> > 4. All comments to note sections are now in the format:
> 
> I vote to drop them completely -- unneeded textual noise.

Perhaps, but it sure makes it easier a lot of times. I'm no machine.. I find it a bit easier to remember where I'm at.

> Use and SGML editor with a build-in parser to find the bounderies.  Sooner or later
> the "comments" will not match the contents any longer...

Well, hopefully the person writing the document would update the comments. You seem to think manual authors are lazy bums. Maybe we all are...


Thanks for the comments, like I said in my first post.. most of this is personal style, but I wanted to submit for other folk's benefit as well. It doesn't really matter much to me if anyone truly adopts this stuff. I'll keep ticking away with my style.

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

-Soli Deo Gloria-

PGP signature