Re: Gnome-App Template Proposed Updates

[Karl Eichwalder <keichwa gmx net>]

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

And advice your editor (Emacs?) to expand an even shorter abbrev:

(define-abbrev-table 'sgml-mode-abbrev-table '(
    ("appg" "&app-gnumeric;" nil 0)
    ))

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

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

/usr/share/sgml/docbk41/50issues.txt doesn't list such a change...  It
isn't that difficult replace sectx with secty -- use Architectural Forms
or sed(1).

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

> 4. All comments to note sections are now in the format:

I vote to drop them completely -- unneeded textual noise.  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...

These are just my thought -- remember: "de gustibus non est disputandum"
;)

-- 
work : ke@suse.de                          |          ------    ,__o
     : http://www.suse.de/~ke/             |         ------   _-\_<,
home : keichwa@gmx.net                     |        ------   (*)/'(*)