Gtk patch version 3, part 1

Gtk patch version 3, part 1

[Jan D.]

[-- Attachment #1: Type: text/plain, Size: 816 bytes --]

Hello.

Here is the third version of this patch.

I think I have fixed most things from the previous version.  Menus
should be faster, I notice a slight improvement, but it never was much
of a problem here.

The flicker in scrollbars should be gone.  Also, the bug for an empty
buffer is fixed.  Geometry problem and the undetachable popup menus
have been fixed.  Help for menus are in now.  A bunch of other bugs,
mostly related to menus, where fixed.

There is some documentation about widget names and how to customize fonts,
but there are some issues with GTK in this area.  Some things will not
be customizable (like the drop down menu in the file dialog), see
http://bugzilla.gnome.org/show_bug.cgi?id=101987.

Things on my todo list for the near future are ChangeLog and NEWS entry, and
GTK toolbar.

	Jan D.

[-- Attachment #2: emacs-diff-gtk.gz --]
[-- Type: application/gzip, Size: 71638 bytes --]

[-- Attachment #3: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://mail.gnu.org/mailman/listinfo/emacs-devel

Re: Gtk patch version 3, part 1

[Richard Stallman]

+ @cindex GTK customize, @file{~/.gtkrc-2.0} file

This is too long for an index entry.  Also, they
don't belong in the same entry.  They should be two entries.

  See documents at
+ @uref{http://www.gtk.org/} for that.

It is not good to refer to a web site for documentation purposes.
Please refer to something that can be included in the user's machine.

    +   Note that this is only for customizing specific GTK widget features.
    + To customize Emacs font, background, faces e.t.c., use the normal
    + X Resources, see @ref{Resources}.

To make this useful, it is important to be at least a little more
specific about which aspects to customize through GTK and which
through X resources.  If you can do this clearly with a description,
that is fine; otherwise you could use a list.

The word "resources" is an ordinary noun, so don't capitailze it.
It should be "etc.", not "e.t.c."

+   For dialogs a GtkDialog is used.

Please avoid the passive voice, here and everywhere, unless
it is absolutely necessary.

    + @example
    + widget_class "GtkWindow.GtkVBox.GtkFixed.GtkVScrollbar" style "my_style"
    + @end example

That line is very long.  It might work ok if you use @smallexample
instead of @example.  Please do that for all the examples in the
section; inconsistency looks bad.

Can this be written as two lines?

+   So the two full paths above are in Emacs the same as:

That's not very clear language.  How about

    Thus, for Emacs you can write the two examples above as:

if that is what you mean.

Re: Gtk patch version 3, part 1

[Jan D.]

> 
> + @cindex GTK customize, @file{~/.gtkrc-2.0} file
> 
> This is too long for an index entry.  Also, they
> don't belong in the same entry.  They should be two entries.

Okay, I just copied the layout from these index entries at the top of the
file:
@cindex X resources, @file{~/.Xdefaults} file
@cindex X resources, @file{~/.Xresources} file

> 
>   See documents at
> + @uref{http://www.gtk.org/} for that.
> 
> It is not good to refer to a web site for documentation purposes.
> Please refer to something that can be included in the user's machine.

Do you mean "that the user can include into his machine" or "something
that might be on the users machine already"?

If the second, can I refer to /usr/share/gtk-doc, where the GTK
documentation is usually installed?

>     +   Note that this is only for customizing specific GTK widget features.
>     + To customize Emacs font, background, faces e.t.c., use the normal
>     + X Resources, see @ref{Resources}.
> 
> To make this useful, it is important to be at least a little more
> specific about which aspects to customize through GTK and which
> through X resources.  If you can do this clearly with a description,
> that is fine; otherwise you could use a list.

It is given by the GTK documentation, is it OK to just refer to that?

> The word "resources" is an ordinary noun, so don't capitailze it.
> It should be "etc.", not "e.t.c."

Changed.

> 
> +   For dialogs a GtkDialog is used.
> 
> Please avoid the passive voice, here and everywhere, unless
> it is absolutely necessary.

How about

  Dialogs in Emacs are GtkDialog widgets.

>     + @example
>     + widget_class "GtkWindow.GtkVBox.GtkFixed.GtkVScrollbar" style "my_style"
>     + @end example
> 
> That line is very long.  It might work ok if you use @smallexample
> instead of @example.  Please do that for all the examples in the
> section; inconsistency looks bad.
> 
> Can this be written as two lines?

It must be one line in the ~/.gtkrc-2.0 file, so I would like to avoid
changing it.

> +   So the two full paths above are in Emacs the same as:
> 
> That's not very clear language.  How about
> 
>     Thus, for Emacs you can write the two examples above as:
> 
> if that is what you mean.

Yes it is, thanks.

	Jan D.

Re: Gtk patch version 3, part 1

[Eric Gillespie]

"Jan D." <jan.h.d@swipnet.se> writes:

> If the second, can I refer to /usr/share/gtk-doc, where the GTK
> documentation is usually installed?

That isn't really a good idea.  That directory might be anywhere:
/usr/share, /usr/local/share, /usr/pkg/share, etc, and it isn't
necessarily in the same prefix as emacs (on my systems, it is in
/usr/pkg but emacs is in /usr/local).  The URL you want to refer
to is:

http://developer.gnome.org/doc/API/2.0/gtk/gtk-Resource-Files.html

It's nigh-impossible for a naive user to navigate from
http://www.gtk.org/ to that document.  Also, i think it satisfies
Richard's suggestion (that the document may be included on a
user's system).

> It is given by the GTK documentation, is it OK to just refer to that?

I think it is better to list it here.

> >     + @example
> >     + widget_class "GtkWindow.GtkVBox.GtkFixed.GtkVScrollbar" style "my_sty
> le"
> >     + @end example

[...]

> It must be one line in the ~/.gtkrc-2.0 file, so I would like to avoid
> changing it.

No, it doesn't have to be on one line.  All whitespace is treated
equally in gtkrc files.  I just tested this in my .gtkrc-2.0.

--  
Eric Gillespie <*> epg@pretzelnet.org

Build a fire for a man, and he'll be warm for a day.  Set a man on
fire, and he'll be warm for the rest of his life. -Terry Pratchett

Re: Gtk patch version 3, part 1

[Eli Zaretskii]

On Tue, 31 Dec 2002, Jan D. wrote:

> There is some documentation about widget names and how to customize fonts,
> but there are some issues with GTK in this area.

I think the "Gtk*" names in this fragment (and also elsewhere):

> +   The top level widget is a GtkWindow that contains a GtkVBox.
> + The GtkVBox contains the GtkMenuBar and a GtkFixed widget.  The vertical
> + scroll bars, GtkVScrollbar, are contained in the GtkFixed widget.
> + The text you write in Emacs is drawn in the GtkFixed widget.

should have the @code markup, as they are programming symbols.

Re: Gtk patch version 3, part 1

[Eli Zaretskii]

On Wed, 1 Jan 2003, Jan D. wrote:

> >     + @example
> >     + widget_class "GtkWindow.GtkVBox.GtkFixed.GtkVScrollbar" style "my_style"
> >     + @end example
> > 
> > That line is very long.  It might work ok if you use @smallexample
> > instead of @example.  Please do that for all the examples in the
> > section; inconsistency looks bad.
> > 
> > Can this be written as two lines?
> 
> It must be one line in the ~/.gtkrc-2.0 file, so I would like to avoid
> changing it.

Any line in an @example that is longer than about 61 characters will 
trigger overfull hbox in TeX.  Any line in @smallexample that is longer 
than 64 characters will do the same.  So it's advisable to break long 
lines into two, even if they must be a single line in actual usage.  You 
can always say in a side note that the line must not be broken.

Re: Gtk patch version 3, part 1

[Jan D.]

> "Jan D." <jan.h.d@swipnet.se> writes:
>
>> If the second, can I refer to /usr/share/gtk-doc, where the GTK
>> documentation is usually installed?
>
> That isn't really a good idea.  That directory might be anywhere:
> /usr/share, /usr/local/share, /usr/pkg/share, etc, and it isn't
> necessarily in the same prefix as emacs (on my systems, it is in
> /usr/pkg but emacs is in /usr/local).  The URL you want to refer
> to is:
>
> http://developer.gnome.org/doc/API/2.0/gtk/gtk-Resource-Files.html
>
> It's nigh-impossible for a naive user to navigate from
> http://www.gtk.org/ to that document.  Also, i think it satisfies
> Richard's suggestion (that the document may be included on a
> user's system).

Okay.

>
>> It is given by the GTK documentation, is it OK to just refer to that?
>
> I think it is better to list it here.

Won't that be a duplication of what is in that URL above?

>
>>>     + @example
>>>     + widget_class "GtkWindow.GtkVBox.GtkFixed.GtkVScrollbar" style 
>>> "my_sty
>> le"
>>>     + @end example
>
> [...]
>
>> It must be one line in the ~/.gtkrc-2.0 file, so I would like to avoid
>> changing it.
>
> No, it doesn't have to be on one line.  All whitespace is treated
> equally in gtkrc files.  I just tested this in my .gtkrc-2.0.

That is good to know!  I'll split the line then.

Thanks,
	Jan D.

Re: Gtk patch version 3, part 1

[Jan D.]

torsdagen den 2 januari 2003 kl 06.52 skrev Eli Zaretskii:

>
> On Tue, 31 Dec 2002, Jan D. wrote:
>
>> There is some documentation about widget names and how to customize fonts,
>> but there are some issues with GTK in this area.
>
> I think the "Gtk*" names in this fragment (and also elsewhere):
>
>> +   The top level widget is a GtkWindow that contains a GtkVBox.
>> + The GtkVBox contains the GtkMenuBar and a GtkFixed widget.  The vertical
>> + scroll bars, GtkVScrollbar, are contained in the GtkFixed widget.
>> + The text you write in Emacs is drawn in the GtkFixed widget.
>
> should have the @code markup, as they are programming symbols.

But is @code valid in the context of a configuration file?  You won't
find these names in the Emacs code.

	Jan D.

Re: Gtk patch version 3, part 1

[Jan D.]

> Any line in an @example that is longer than about 61 characters will
> trigger overfull hbox in TeX.  Any line in @smallexample that is longer
> than 64 characters will do the same.  So it's advisable to break long
> lines into two, even if they must be a single line in actual usage.  You
> can always say in a side note that the line must not be broken.

Thanks for the figures, but now that Eric Gillespie pointed out that
the line can indeed be broken, I wil do that.

	Jan D.

Re: Gtk patch version 3, part 1

[Kim F. Storm]

Richard Stallman <rms@gnu.org> writes:

>   See documents at
> + @uref{http://www.gtk.org/} for that.
> 
> It is not good to refer to a web site for documentation purposes.
> Please refer to something that can be included in the user's machine.

Richard,
Could you please clarify the second part of this statement?

I agree that simply refering to a web site isn't good, but IMO it
should be perfectly ok to refer to a specific document on the web
(giving its complete URL.)

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: Gtk patch version 3, part 1

[Eli Zaretskii]

> Date: Thu, 2 Jan 2003 09:05:51 +0100
> From: "Jan D." <jan.h.d@swipnet.se>
> >
> >> +   The top level widget is a GtkWindow that contains a GtkVBox.
> >> + The GtkVBox contains the GtkMenuBar and a GtkFixed widget.  The vertical
> >> + scroll bars, GtkVScrollbar, are contained in the GtkFixed widget.
> >> + The text you write in Emacs is drawn in the GtkFixed widget.
> >
> > should have the @code markup, as they are programming symbols.
> 
> But is @code valid in the context of a configuration file?

Yes.  It is customary to use @code even for menu items, just to make
them stand out in print.

Re: Gtk patch version 3, part 1

[Richard Stallman]

    > It is not good to refer to a web site for documentation purposes.
    > Please refer to something that can be included in the user's machine.

    Do you mean "that the user can include into his machine" or "something
    that might be on the users machine already"?

I mean something that ought to be on the user's machine
(though any given user may or may not have installed it, of course).

    If the second, can I refer to /usr/share/gtk-doc, where the GTK
    documentation is usually installed?

Yes, but isn't there an Info file for GTK?

    >     +   Note that this is only for customizing specific GTK widget features.
    >     + To customize Emacs font, background, faces e.t.c., use the normal
    >     + X Resources, see @ref{Resources}.
    > 
    > To make this useful, it is important to be at least a little more
    > specific about which aspects to customize through GTK and which
    > through X resources.  If you can do this clearly with a description,
    > that is fine; otherwise you could use a list.

    It is given by the GTK documentation, is it OK to just refer to that?

A brief explicit concrete list would be much better than a
cross-reference.  When something is directly relevant for the user's
understanding, using a cross reference is considerably less convenient
for the user.

    > +   For dialogs a GtkDialog is used.
    > 
    > Please avoid the passive voice, here and everywhere, unless
    > it is absolutely necessary.

    How about

      Dialogs in Emacs are GtkDialog widgets.

Exactly!

Re: Gtk patch version 3, part 1

[Richard Stallman]

    >> + scroll bars, GtkVScrollbar, are contained in the GtkFixed widget.
    >> + The text you write in Emacs is drawn in the GtkFixed widget.
    >
    > should have the @code markup, as they are programming symbols.

    But is @code valid in the context of a configuration file?

@code is for any symbol name or command name that would appear in any
kind of code.  It is not specifically for Emacs Lisp.

Re: Gtk patch version 3, part 1

[Richard Stallman]

    I agree that simply refering to a web site isn't good, but IMO it
    should be perfectly ok to refer to a specific document on the web
    (giving its complete URL.)

Whether the URL is to the precise page or the front page isn't the
issue.  Neither one is the right thing to do here.  Either way, the
reference is to a location not on the user's own machine.

We should always refer to a documentation file that is (or
could/should be) on the user's *own machine*.  

Re: Gtk patch version 3, part 1

[Richard Stallman]

    Any line in an @example that is longer than about 61 characters will 
    trigger overfull hbox in TeX.  Any line in @smallexample that is longer 
    than 64 characters will do the same.

The font used in @smallexample is considerably smaller than the one
for @example--I am sure the difference in capacity is more than just 3
characters.

Re: Gtk patch version 3, part 1

[Richard Stallman]

    Okay, I just copied the layout from these index entries at the top of the
    file:
    @cindex X resources, @file{~/.Xdefaults} file
    @cindex X resources, @file{~/.Xresources} file

I will fix those too.
Thanks.

Re: Gtk patch version 3, part 1

[Alfred M. Szmidt]

       If the second, can I refer to /usr/share/gtk-doc, where the GTK
       documentation is usually installed?

   Yes, but isn't there an Info file for GTK?

Very outdated info pages exist.  GTK uses (from what I gather) HTML
files that get generated from SGML files.

Re: Gtk patch version 3, part 1

[Eric Gillespie]

"Jan D." <jan.h.d@swipnet.se> writes:

> Won't that be a duplication of what is in that URL above?

Not exactly.  While the raw information would be the same, you
won't find the list of which emacs elements to customize with X
resources and which to customize with gtkrc on gtk.org.
Re-formulating the information to give the emacs user exactly
what she means would be a valuable form of duplication.  I don't
think the text you currently have in this part of the manual is
far off from what is needed; it just needs to be expanded a bit.

--  
Eric Gillespie <*> epg@pretzelnet.org

Build a fire for a man, and he'll be warm for a day.  Set a man on
fire, and he'll be warm for the rest of his life. -Terry Pratchett

Re: Gtk patch version 3, part 1

[Eric Gillespie]

Richard Stallman <rms@gnu.org> writes:

> We should always refer to a documentation file that is (or
> could/should be) on the user's *own machine*.

That isn't really feasible in this case.  There is no standard
location where this document would be installed.  Worse, the
document we are describing isn't even end-user documentation.
Such beast does not yet exist :(.

--  
Eric Gillespie <*> epg@pretzelnet.org

Build a fire for a man, and he'll be warm for a day.  Set a man on
fire, and he'll be warm for the rest of his life. -Terry Pratchett

Re: Gtk patch version 3, part 1

[Robert J. Chassell]

       Do you mean "that the user can include into his machine" or "something
       that might be on the users machine already"?

   I mean something that ought to be on the user's machine
   (though any given user may or may not have installed it, of course).

Yes.  If it is not on your machine, you may not be able to access it:

 * The site may be down, as I find happens with the places I reference.

 * Your Internet service provider may have suffered a hardware
   failure, as mine did on 31 Dec 2002.

 * Getting something on the net may be inconvenient or expensive.  I
   was just talking to one of my my brothers-in-law: for him to get
   an update is expensive.  It takes time to download an update.
   

       If the second, can I refer to /usr/share/gtk-doc, where the GTK
       documentation is usually installed?

The /usr/share/doc/ documents are so much less convenient than Texinfo
documents.  For one, the Texinfo documents go into Info, which is
still, after 15 years, the single most efficient of the online
documentation formats (since you can navigate using regexps).  For
two, Texinfo documents go into HTML.  For three, Texinfo documents can
be typeset and printed, from DVI, PS, or PDF formatted files.

/usr/share/doc/ documents tend to be either text or HTML, both of
which have been superceded by better formats.  (HTML was superceded by
a format developed before CERN started using it.  Of course, the
people at CERN never thought that their format would be used for more
than the equivalent of 1980s Apple Hypertext Cards, which is why they
did not insist on an efficient language.  It never occurred to the
managers at CERN that anyone would want to reference another page of
the same document; all documents would be one page long!)

   A brief explicit concrete list would be much better than a
   cross-reference.  When something is directly relevant for the
   user's understanding, using a cross reference is considerably less
   convenient for the user.

Yes: please remember, when people look up a reference, you have to
think of them as being in `encyclopedia mode'.  They want the
information.  A link to another document on their machine is likely to
be perceived as a hinderance.  (A link to a document that they cannot
get to, because it is on another machine and they are off the
Internet, is likely to be perceived as a failure of the
documentation.)

-- 
    Robert J. Chassell                         Rattlesnake Enterprises
    http://www.rattlesnake.com                  GnuPG Key ID: 004B4AC8
    http://www.teak.cc                             bob@rattlesnake.com

Re: Gtk patch version 3, part 1

[Kim F. Storm]

"Robert J. Chassell" <bob@rattlesnake.com> writes:

>        Do you mean "that the user can include into his machine" or "something
>        that might be on the users machine already"?
> 
>    I mean something that ought to be on the user's machine
>    (though any given user may or may not have installed it, of course).
> 
> Yes.  If it is not on your machine, you may not be able to access it:

Well if it is not on your machine -- you definitely cannot access it 
without accessing the Internet.

I don't argue that if there is a document on your -- and everyone
else's -- local machines that can be referenced, we should do that.

But I really don't see how we can assume that a specific file is
always available.  Some systems even come without man-pages ...

If we cannot rely on having a local file, we have two options:

- include the necessary documentation in the emacs distribution [meaning
  that we may have to (re)write that documentation ourselves], or

- reference an existing document (in whatever format it is available in)
  with the appropriate URL.

The first option still costs you something (when downloading and
storing emacs on your local machine), and it may be time-consuming to
write the necessary documentation.

The second option has the potential risks of non-availability that you
mention, and it *may* also costs a few cents to access the URL (although
flat-rate Internet access is getting pretty common in many places).

IMHO, referencing a URL is at least as good as referencing a local
file which we cannot be sure is available (or don't know where it's
located even if it exists)...

Having said that, I agree that Texinfo is a superior format for
online docs!

> Yes: please remember, when people look up a reference, you have to
> think of them as being in `encyclopedia mode'.  They want the
> information.  A link to another document on their machine is likely to
> be perceived as a hinderance.  

If it is a link which they can click on with mouse-2 and have it
opened in an emacs buffer, in a browser or in some other viewer, I
think most users will be happy with that.

>                                (A link to a document that they cannot
> get to, because it is on another machine and they are off the
> Internet, is likely to be perceived as a failure of the
> documentation.)

I disagree!  Regarding a user's inability to access the Internet as a
documentation failure seems quite far-fetched to me.

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: Gtk patch version 3, part 1

[Luc Teirlinck]

Kim Storm wrote:

   - include the necessary documentation in the emacs distribution [meaning
     that we may have to (re)write that documentation ourselves], or

I do not understand.  Why would it need to be rewritten?  Is GTK and
its documentation free software?  If we want it in the superior
Texinfo format, of course, but what if we are (reluctantly) willing to
use the html files as they are?  That is all the URL would provide
anyway.  The document does not seem to be that huge.  I took a look at
it.  Over a slow internet connection.  Plenty of "10k read stalled".
Forever.  Interrupt transfer. Try again...  More of the same.  No fun.
Note also that with an URL, you first have to remember to connect to
the internet before you can double-click with mouse 2.  Depending on
the situation, getting connected can take a non-trivial amount of
time.

I actually have the documents in /usr/share/doc.  If I did not and
needed them, I guess that in the worst case I could use wget to get
things on my own machine.  Do the GTK people not provide more
convenient ways than using wget?  I could not find any on the site.

Anyway, why not just include it in the Emacs distribution?
Alternative solutions might be searching for the documentation in the
user's file system or having the location provided by the user in some
Emacs variable.

Any of this as an intermediate solution until somebody finds the time
to write a suitable Texinfo documentation.

Sincerely,

Luc.

Re: Gtk patch version 3, part 1

[Luc Teirlinck]

>From my previous message:

   Do the GTK people not provide more
   convenient ways than using wget?  I could not find any on the site.

That is because I did not look very well:

A packaged verion of this tutorial is available from
ftp://ftp.gtk.org/pub/gtk/tutorial which contains the tutorial in
various different formats. This package is primary for those people
wanting to have the tutorial available for offline reference and for
printing.

Sincerely,

Luc.

Re: Gtk patch version 3, part 1

[Luc Teirlinck]

>From my previous message:

   A packaged verion of this tutorial is available from
   ftp://ftp.gtk.org/pub/gtk/tutorial which contains the tutorial in
   various different formats. This package is primary for those people
   wanting to have the tutorial available for offline reference and for
   printing.

I believe I failed to make clear that this is quoted literally from
the GTK site and not my own remarks.

Sincerely,

Luc.

Re: Gtk patch version 3, part 1

[Richard Stallman]

    Very outdated info pages exist.  GTK uses (from what I gather) HTML
    files that get generated from SGML files.

What exactly is the format?  Is it Docbook?

Texinfo/info: scrolling images (Re: Gtk patch version 3, part 1)

[Karl Eichwalder]

storm@cua.dk (Kim F. Storm) writes:

> Having said that, I agree that Texinfo is a superior format for
> online docs!

As usual, it depends ;) As it stands, it's somehow related to monospaced
fonts (info viewer like Emacs must obey hardcoded line breaks) and, more
important, the info file format still lack image support.  Aside: Emacs
cannot scroll incline images properly--or did something change in CVS
head the last 2 month in the area? (Cf. etc/TODO.)

> If it is a link which they can click on with mouse-2 and have it
> opened in an emacs buffer, in a browser or in some other viewer, I
> think most users will be happy with that.

BTW, you'd better use @uref instead of @url.  Further, why not
providing both locations at the same time, a local and a remote
reference?

-- 
ke@suse.de (work) / keichwa@gmx.net (home):              |
http://www.gnu.franken.de/ke/                            |      ,__o
Free Translation Project:                                |    _-\_<,
http://www.iro.umontreal.ca/contrib/po/HTML/             |   (*)/'(*)

Re: Gtk patch version 3, part 1

[Jan D.]

> 
> I do not understand.  Why would it need to be rewritten?  Is GTK and
> its documentation free software?  If we want it in the superior
> Texinfo format, of course, but what if we are (reluctantly) willing to
> use the html files as they are?  That is all the URL would provide
> anyway.  The document does not seem to be that huge.  I took a look at
> it.  Over a slow internet connection.  Plenty of "10k read stalled".
> Forever.  Interrupt transfer. Try again...  More of the same.  No fun.

That is what I mean, rewritten to texinfo.  I think this is a must
for Emacs documentation.

> Anyway, why not just include it in the Emacs distribution?

There is the problem of keeping it up to date.  I know the format
for GTK resources changed a bit from 1.2 to 2.0 (added font_name),
I haven't looked if 2.2 has any changes. 
Who knows what 2.4 will look like?

	Jan D.

Re: Gtk patch version 3, part 1

[Jan D.]

> 
>    A packaged verion of this tutorial is available from
>    ftp://ftp.gtk.org/pub/gtk/tutorial which contains the tutorial in
>    various different formats. This package is primary for those people
>    wanting to have the tutorial available for offline reference and for
>    printing.
> 
> I believe I failed to make clear that this is quoted literally from
> the GTK site and not my own remarks.

I think the API reference is a better starting point for documentation
in Emacs, as the tutorial leaves out some important things, like
base, engine, fontset, font_name, include, etc.

	Jan D.

Re: Gtk patch version 3, part 1

[Alfred M. Szmidt]

       Very outdated info pages exist.  GTK uses (from what I gather) HTML
       files that get generated from SGML files.

   What exactly is the format?  Is it Docbook?

No, it is not Docbook, it uses `linuxdoc' (no idea what that is).  To
quote the first page I found about this format:

 "Linuxdoc-SGML is a text-formatting package based on SGML (Standard
 Generalized Markup Language), which allows you to produce LaTeX,
 groff, HTML, and plain ASCII (via groff) documents from a single
 source. Texinfo support is forthcoming; due to the flexible nature of
 SGML many other target formats are possible."

 "This system is tailored for writing technical software
 documentation, an example of which are the Linux HOWTO
 documents. However, there is nothing Linux-specific about this
 package; it can be used for many other types of documentation on many
 other systems. The name is simply derived from its use for the Linux
 HOWTO documents. It should be useful for all kinds of printed and
 online documentation."

Re: Gtk patch version 3, part 1

[Alfred M. Szmidt]

   That is what I mean, rewritten to texinfo.  I think this is a must
   for Emacs documentation.

I don't really think there is a need to rewrite it, if you can convert
it to texinfo.  And then the info pages should be distributed by
default with the project.

Re: Gtk patch version 3, part 1

[Alex Schroeder]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:

> I actually have the documents in /usr/share/doc.  If I did not and
> needed them, I guess that in the worst case I could use wget to get
> things on my own machine.  Do the GTK people not provide more
> convenient ways than using wget?  I could not find any on the site.

Is the documentation not in DocBook format, so that we can generate
texinfo files from it (eventhough they were not of the greatest
quality last time I looked).

Alex.

Re: Gtk patch version 3, part 1

[Alex Schroeder]

"Alfred M. Szmidt" <ams@kemisten.nu> writes:

> No, it is not Docbook, it uses `linuxdoc' (no idea what that is).  To
> quote the first page I found about this format:
>
>  "Linuxdoc-SGML is a text-formatting package based on SGML (Standard
>  Generalized Markup Language), which allows you to produce LaTeX,
>  groff, HTML, and plain ASCII (via groff) documents from a single
>  source. Texinfo support is forthcoming; due to the flexible nature of
>  SGML many other target formats are possible."

I thought this was just the old name for docbook.  Searching for
"linuxdoc docbook" on Google found many messages that explain how to
convert one into the other, so eventhough they are not the same, they
can be converted into each other.

Alex.

Re: Gtk patch version 3, part 1

[Luc Teirlinck]

Jan D. wrote:
   
   I think the API reference is a better starting point for documentation
   in Emacs, as the tutorial leaves out some important things, like
   base, engine, fontset, font_name, include, etc.

Sorry, I misunderstood which document you were referring to.  I agree
that manuals are better for documentation than tutorials, which tend
to be incomplete.  I do not seem to have the API reference in
/usr/share/doc, only the tutorial, which is why I assumed that was what
you were referring to.

Anyway, if the document can be automatically converted to Texinfo, as
Alfred and Alex suggest and if GTK were willing to distribute the
Texinfo form with the project, then that completely solves the
problem anyway.

Sincerely,

Luc.

Re: Gtk patch version 3, part 1

[Jan D.]

Luc Teirlinck wrote:
> Jan D. wrote:
>    
>    I think the API reference is a better starting point for documentation
>    in Emacs, as the tutorial leaves out some important things, like
>    base, engine, fontset, font_name, include, etc.
> 
> Sorry, I misunderstood which document you were referring to.  I agree
> that manuals are better for documentation than tutorials, which tend
> to be incomplete.  I do not seem to have the API reference in
> /usr/share/doc, only the tutorial, which is why I assumed that was what
> you were referring to.

When I installed GTK in prefix, the API documents got installed in 
prefix/share/gtk-doc, not prefix/share/doc.  I would have looked in 
prefix/share/doc first also.


	Jan D.

Re: Gtk patch version 3, part 1

[Raja R Harinath]

Hi,

"Alfred M. Szmidt" <ams@kemisten.nu> writes:

>        Very outdated info pages exist.  GTK uses (from what I gather) HTML
>        files that get generated from SGML files.
>
>    What exactly is the format?  Is it Docbook?
>
> No, it is not Docbook, it uses `linuxdoc' (no idea what that is).  To
> quote the first page I found about this format:

Are you sure?  I have a CVS version of GTK+ check out, and 

  head gtk+/docs/reference/gdk/gdk-docs.sgml

gives:

   <?xml version="1.0"?>
   <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                  "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
   <!ENTITY gdk-General SYSTEM "xml/general.xml">
   <!ENTITY gdk-Bitmaps-and-Pixmaps SYSTEM "xml/pixmaps.xml">
   <!ENTITY gdk-Images SYSTEM "xml/images.xml">
   <!ENTITY gdk-GdkRGB SYSTEM "xml/rgb.xml">
   <!ENTITY gdk-Pixbufs SYSTEM "xml/pixbufs.xml">
   <!ENTITY gdk-Colormaps-and-Colors SYSTEM "xml/colors.xml">
   <!ENTITY gdk-Fonts SYSTEM "xml/fonts.xml">

Anything that uses 'gtk-doc' uses DocBook.

- Hari
-- 
Raja R Harinath ------------------------------ harinath@cs.umn.edu

Re: Gtk patch version 3, part 1

[Luc Teirlinck]

Jan D. wrote:
   
   When I installed GTK in prefix, the API documents got installed in 
   prefix/share/gtk-doc, not prefix/share/doc.  I would have looked in 
   prefix/share/doc first also.

On my system (Red Hat 7.2) I not only do not have a
usr/share/gtk-doc (I have a usr/share/gtkhtml, but that seems to be
something completely different), find / -name '*gtk-doc' fails to find
anything.  I gather from what you say, however that it "should" be
there and that if I upgraded to the latest GTK version it would be
there.

Anyway, if we can get Texinfo files, all of this seems irrelevant.

Sincerely,

Luc.

Re: Gtk patch version 3, part 1

[Eric Gillespie]

"Robert J. Chassell" <bob@rattlesnake.com> writes:

> Yes.  If it is not on your machine, you may not be able to
> access it:

[...]

That may be so, but the fact remains that something is better
than nothing.  We can duplicate all the end-user information from
this document (bad idea), or we can make the cross-reference to
the URL with a note saying that this document mayb be available
on your system in $prefix/share/gtk-doc/html/gtk where $prefix is
the prefix gtk was installed to.

--  
Eric Gillespie <*> epg@pretzelnet.org

Build a fire for a man, and he'll be warm for a day.  Set a man on
fire, and he'll be warm for the rest of his life. -Terry Pratchett

Re: Gtk patch version 3, part 1

[Eric Gillespie]

"Alfred M. Szmidt" <ams@kemisten.nu> writes:

> No, it is not Docbook, it uses `linuxdoc' (no idea what that is).  To
> quote the first page I found about this format:

This is not true.  Perhaps older versions used linuxdoc (gtk is
notoriously bad for leaving old documentation lying around where
people can find it), but the GNOME and GTK projects have
standardized on docbook.

>  "Linuxdoc-SGML is a text-formatting package based on SGML (Standard

Furthermore GTK and GNOME use XML, not SGML.

--  
Eric Gillespie <*> epg@pretzelnet.org

Build a fire for a man, and he'll be warm for a day.  Set a man on
fire, and he'll be warm for the rest of his life. -Terry Pratchett

Re: Gtk patch version 3, part 1

[Eric Gillespie]

[assuming this was supposed to go to the list]

Richard Stallman <rms@gnu.org> writes:

>     That isn't really feasible in this case.  There is no standard
>     location where this document would be installed.
> 
> That seems like quite a problem.

It is a problem, but only a minor one.

> 						      Worse, the
>     document we are describing isn't even end-user documentation.
>     Such beast does not yet exist :(.
> 
> Are you saying that this particular end-user documentation has not yet
> been written for GTK?

What i am saying is that there is *no* end user documentation
for gtk.  I believe all the raw information is available in the
API docs to which we have been referring in this thread, but no
one has yet made the effort to extract the information relevant
to end users and form it into useful end-user documentation.

That would be a valuable project for someone to take on.  Just
make sure this document is installed on the system so emacs can
refer to it :).

--  
Eric Gillespie <*> epg@pretzelnet.org

Build a fire for a man, and he'll be warm for a day.  Set a man on
fire, and he'll be warm for the rest of his life. -Terry Pratchett

Re: Gtk patch version 3, part 1

[Alfred M. Szmidt]

   > No, it is not Docbook, it uses `linuxdoc' (no idea what that is).
   > To quote the first page I found about this format:

   This is not true.  Perhaps older versions used linuxdoc (gtk is
   notoriously bad for leaving old documentation lying around where
   people can find it), but the GNOME and GTK projects have
   standardized on docbook.

Then I had to be looking at some old copy.

Re: Gtk patch version 3, part 1

[Luc Teirlinck]

>From my previous message:

   On my system (Red Hat 7.2) I not only do not have a
   usr/share/gtk-doc (I have a usr/share/gtkhtml, but that seems to be
   something completely different), find / -name '*gtk-doc' fails to find
   anything.

Actually, I take this partially back.  I have access to two computers
with a Red Hat 7.2 system on it.  The one that has no
/usr/share/gtk-doc is one that came pre-installed with the computer I
purchased.  I installed Red Hat 7.2 myself on the other.  The Red Hat
I installed myself does have /usr/share/gtk-doc.

Sincerely,

Luc.

Re: Gtk patch version 3, part 1

[Eric Gillespie]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:

> >From my previous message:
> 
>    On my system (Red Hat 7.2) I not only do not have a
>    usr/share/gtk-doc (I have a usr/share/gtkhtml, but that seems to be
>    something completely different), find / -name '*gtk-doc' fails to find
>    anything.
> 
> Actually, I take this partially back.  I have access to two computers
> with a Red Hat 7.2 system on it.  The one that has no
> /usr/share/gtk-doc is one that came pre-installed with the computer I
> purchased.  I installed Red Hat 7.2 myself on the other.  The Red Hat
> I installed myself does have /usr/share/gtk-doc.

It's funny that today, as we're talking about this, i see that
NetBSD has changed gtk and related packages to install the
documentation in share/doc/html/$package rather than
share/gtk-doc/html/$package.  This only reinforces the point that
the emacs manual cannot really rely on this document's location
even if it is installed on the system.

--  
Eric Gillespie <*> epg@pretzelnet.org

Build a fire for a man, and he'll be warm for a day.  Set a man on
fire, and he'll be warm for the rest of his life. -Terry Pratchett

Re: Gtk patch version 3, part 1

[Luc Teirlinck]

Eric Gillespie wrote:

   It's funny that today, as we're talking about this, i see that
   NetBSD has changed gtk and related packages to install the
   documentation in share/doc/html/$package rather than
   share/gtk-doc/html/$package.  This only reinforces the point that
   the emacs manual cannot really rely on this document's location
   even if it is installed on the system.

But would that problem not go away, if the documentation were
converted to Texinfo format, which can be done automatically, and if
GTK would install those in one of the standard places that info looks
at?

Sincerely,

Luc.

Re: Gtk patch version 3, part 1

[Eric Gillespie]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:

> But would that problem not go away, if the documentation were
> converted to Texinfo format, which can be done automatically,
> and if GTK would install those in one of the standard places
> that info looks at?

It would.  Better still would be to write end-user documentation
and convert that into Texinfo.

--  
Eric Gillespie <*> epg@pretzelnet.org

Build a fire for a man, and he'll be warm for a day.  Set a man on
fire, and he'll be warm for the rest of his life. -Terry Pratchett

Re: Gtk patch version 3, part 1

[Richard Stallman]

    But I really don't see how we can assume that a specific file is
    always available.  Some systems even come without man-pages ...

That is not a real issue.  Documentation files can refer to other
documentation files; whether any of these files is installed on the
machine is the user's own issue.

Re: Gtk patch version 3, part 1

[Richard Stallman]

People seem to be arguing about a question that isn't real.

When information is directly relevant to the topic, a cross reference
to another manual (or even another section) is inconvenient for the
user.  It is much better to duplicate a small amount of information
than to ask the user to find it elsewhere.

The Emacs Manual should tell people enough information that they can
customize Emacs.

Re: Gtk patch version 3, part 1

[Robert J. Chassell]

   > Yes.  If it is not on your machine, you may not be able to access it:

   Well if it is not on your machine -- you definitely cannot access it
   without accessing the Internet.

That is false!  I do not access over the Internet most of the material
that is not on my machine.  You must be living in a rich and different
world!  Mostly, I get software and documentation from CDs.  It would
take me over 500 hours to download the Debian CDs that I use.

We must rely on `having a local file', meaning a file that is a part
of a standard distribution, and either on a user's machine, or less
conveniently, on a CD or other inexpensive transport media.

This means that we must continue to write documentation and provide it
to the user.

    Some systems even come without man-pages ...

and some come without Info.

As a child, I enjoyed a cartoon in which the hero purchased an
inexpensive, second-hand car that drove very quietly down the steep
hill from the car dealership ....  but the car refused to go up the
next hill ...  our cartoon hero then discovered that the car lacked an
engine ....

An instance of Emacs without documentation is as broken as a car
without a motor.  The people who make distributions without man-pages
and Info are as crooked as the worst second-hand car salesmen.


   > Yes: please remember, when people look up a reference, you have to
   > think of them as being in `encyclopedia mode'.  They want the
   > information.  A link to another document on their machine is likely to
   > be perceived as a hinderance.

   If it is a link which they can click on with mouse-2 and have it
   opened in an emacs buffer, in a browser or in some other viewer, I
   think most users will be happy with that.

No, in my rather extensive experience, people are not happy with that.
After they learn about incremental search and regexps, and the
convenience of proper documentation, most people I know prefer it.

Unfortunately, many contemporary people have learned from interfaces
that were thrown out a quarter century ago by people who had
experience then.  These people have not learned by using decent
software, so they still think that computers are `better typewriters',
and that documentation should be as awkward as you find in man pages
or Web pages or in PDF documents.  That failure is a fault of the
suppliers and schools that persist on using trailing edge technology.

You harm everyone by saying that `most users will be happy with an
awkward interface' when you the truth is that `most users will be
happy with a 1960s user interface so long as they don't know that an
even better interface has been available for more than a generation'.


   > (A link to a document that they cannot
   > get to, because it is on another machine and they are off the
   > Internet, is likely to be perceived as a failure of the
   > documentation.)

   I disagree!  Regarding a user's inability to access the Internet as a
   documentation failure seems quite far-fetched to me.

Again, it appears to me that you are living in a limited world of
intelligent and well connected geeks.  In my experience, I have found
that most people do not think of documentary `help' as meaning that
they have to get off the telephone with me, plug the computer into the
telephone line, dial the connection, and then pay for the download
time on a per minute basis.  They think they should be able to run the
help function, and find out what they did wrong.

For example -- and I will not tell you who among my relatives made
this mistake less than two weeks ago -- you need to tell GNU where you
are located if you want to see which stars are visible at your current
time and location....

--
    Robert J. Chassell                         Rattlesnake Enterprises
    http://www.rattlesnake.com                  GnuPG Key ID: 004B4AC8
    http://www.teak.cc                             bob@rattlesnake.com

Re: Gtk patch version 3, part 1

[Alfred M. Szmidt]

   What's wrong about specifying a URL where you can access it?

The user is being forced to connect to the internet just to be able to
read the documentation, thats whats wrong.  This can be inconvinet,
expensive or just plain impossible.

Re: Gtk patch version 3, part 1

[Kim F. Storm]

"Robert J. Chassell" <bob@rattlesnake.com> writes:

>    > Yes.  If it is not on your machine, you may not be able to access it:
> 
>    Well if it is not on your machine -- you definitely cannot access it
>    without accessing the Internet.
> 
> That is false!  I do not access over the Internet most of the material
> that is not on my machine.  You must be living in a rich and different
> world!  Mostly, I get software and documentation from CDs.  It would
> take me over 500 hours to download the Debian CDs that I use.

The basic statement is not false!  If the document is not on your
machine, you cannot access it locally.  If I have to choose between
swapping CDs or visiting a URL, I'd choose the URL.  But if the file
you need is on a CD of yours, why didn't you install it locally in the
first place?

I'm arguing about files which ARE NOT AVAILABLE LOCALLY.

What's wrong about specifying a URL where you can access it?
As a user, you are free(!) to follow or ignore the URL.

> We must rely on `having a local file', meaning a file that is a part
> of a standard distribution, and either on a user's machine, or less
> conveniently, on a CD or other inexpensive transport media.

I fully agree that having an local, well-written info file is much
better than having to rely on a remote HTML or PDF document.

But in my experience, you cannot rely on any specific documentation to
be available locally -- unless you include that documentation as part
of your own software distribution -- and even in that case, there's no
guarantee that whoever puts your software into a distribution will
also include the docs....

> 
> This means that we must continue to write documentation and provide it
> to the user.
> 

Exactly!  The real issue is to write the necessary documentation and
include it in the emacs distribution.

Until that's done, I don't see what's wrong with supplying a URL
where you can find the  "best docs currently available" .

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: Gtk patch version 3, part 1

[Robert J. Chassell]

   "Robert J. Chassell" <bob@rattlesnake.com> writes:

   >    > Yes.  If it is not on your machine, you may not be able to access it:
   > 
   >    Well if it is not on your machine -- you definitely cannot access it
   >    without accessing the Internet.
   > 
   > That is false!  I do not access over the Internet most of the material
   > that is not on my machine.  You must be living in a rich and different
   > world!  Mostly, I get software and documentation from CDs.  It would
   > take me over 500 hours to download the Debian CDs that I use.

   The basic statement is not false!  If the document is not on your
   machine, you cannot access it locally.  

That is not true!  I can and often do access documents and programs
locally that are not on my machine.  I put in a CD.  A CD is less
convenient than accessing the document on my machine, but it is local.

   ... If I have to choose between swapping CDs or visiting a URL, I'd
   choose the URL.

This means you have a fast and inexpensive Internet connection.  I
envy you.  

If I have a choice between spending a great deal of time visiting a
URL or spending one-hundreth that time downloading from a local CD, I
use the CD.

   But if the file you need is on a CD of yours, why didn't you
   install it locally in the first place?

Because I don't know that I want it -- often I don't know that the
document exists.  The only part of my Debian CD set that is on my
local machine is the table of contents.

   I'm arguing about files which ARE NOT AVAILABLE LOCALLY.

   What's wrong about specifying a URL where you can access it?
   As a user, you are free(!) to follow or ignore the URL.

Because you should plan to create documents that can be made available
locally.  If you specify a URL, a GNU distributor is not likely to put
that document on a CD or on a hard drive.  The distributor probably
does not ever know about the document.

If you create a situation in which the document fails to reach the
user, you have told the user you do not think it worth providing
resources to them.

   I fully agree that having an local, well-written info file is much
   better than having to rely on a remote HTML or PDF document.

That is the whole point.  If you make it a policy that a remote
document substitutes for a local document, then everyone loses.

This is because many of the GNU distributors and hackers have cheap,
convenient, and fast Internet access for themselves and do not have
correspondents who live in Bennington, VT, USA or in Cameroon, in
Africa, correspondents whose Internet connections are slow and
expensive.  Such distributors and hackers often have no reason to
think of the rest of us.  


   But in my experience, you cannot rely on any specific documentation to
   be available locally -- unless you include that documentation as part
   of your own software distribution -- and even in that case, there's no
   guarantee that whoever puts your software into a distribution will
   also include the docs....

That is true; but the key point is that whoever puts your software
into a distribution is much more likely to include documentation if
you provide it to them than if you do not provide it to them.

   Exactly!  The real issue is to write the necessary documentation and
   include it in the emacs distribution.

   Until that's done, I don't see what's wrong with supplying a URL
   where you can find the  "best docs currently available" .

It is very wrong supply a URL rather than the documentation to which
it points.  The reason is that supplying just the URL reduces the
motivation many people have to create local documentation.  I possess
the contents of URLs on my local machine:  often it is in an
inefficient HTML format rather than plain text or Texinfo, but it
better than none.  None is what you are actually talking about for
many people if the document is not part of a CD distribution or on a
local hard disk.

-- 
    Robert J. Chassell                         Rattlesnake Enterprises
    http://www.rattlesnake.com                  GnuPG Key ID: 004B4AC8
    http://www.teak.cc                             bob@rattlesnake.com

Re: Gtk patch version 3, part 1

[Richard Stallman]

It's not a matter of rewriting the GTK documentation.  The point is to
write what the Emacs user specifically needs to know.  The part of the
Emacs manual that talks about customizing Xlib and the Lucid widgets
isn't the same as anything in the manuals for X or Xt.  They don't
do this job; they do their jobs.  It's the same for GTK.

Re: Gtk patch version 3, part 1

[Richard Stallman]

    Anyway, if the document can be automatically converted to Texinfo, as
    Alfred and Alex suggest and if GTK were willing to distribute the
    Texinfo form with the project, then that completely solves the
    problem anyway.

They don't necessarily need to distribute the Texinfo file; it is
enough if they have makefile targets to produce Info and DVI files
from their source files.

But none of that substitutes for writing the text that needs to be in
the Emacs manual.  Pointing to GTK documentation is good for telling
the user where to find more info about GTK, but the essential points
about customizing Emacs should be given in the Emacs manual, focusing
specifically on Emacs, addressed to Emacs users.

Re: Gtk patch version 3, part 1

[Richard Stallman]

    What i am saying is that there is *no* end user documentation
    for gtk.  I believe all the raw information is available in the
    API docs to which we have been referring in this thread, but no
    one has yet made the effort to extract the information relevant
    to end users and form it into useful end-user documentation.

    That would be a valuable project for someone to take on.

I agree.  In fact, it may be hard for us to figure out what to say in
the Emacs manual without official end-user documentation to get the
information from.  I hope someone knows enough to be able to figure
out what we should say in the Emacs manual.

Re: Gtk patch version 3, part 1

[Eric Gillespie]

Richard Stallman <rms@gnu.org> writes:

> People seem to be arguing about a question that isn't real.

The question is real.  The emacs manual needs information about
how to customize the gtk widgets, yes, but it is not the place to
document the gtkrc syntax, any more than it is the place to
document the syntax of X resources.  For this, a cross-reference
is valuable.

--  
Eric Gillespie <*> epg@pretzelnet.org

Build a fire for a man, and he'll be warm for a day.  Set a man on
fire, and he'll be warm for the rest of his life. -Terry Pratchett

Re: Gtk patch version 3, part 1

[Eric Gillespie]

Richard Stallman <rms@gnu.org> writes:

> I agree.  In fact, it may be hard for us to figure out what to
> say in the Emacs manual without official end-user documentation
> to get the information from.  I hope someone knows enough to be
> able to figure out what we should say in the Emacs manual.

Having real end-user documentation for gtk would be valuable,
yes.  But as i said before, the raw information is available.  So
figuring out what to say in the emacs manual is not difficult.

--  
Eric Gillespie <*> epg@pretzelnet.org

Build a fire for a man, and he'll be warm for a day.  Set a man on
fire, and he'll be warm for the rest of his life. -Terry Pratchett

Re: Gtk patch version 3, part 1

[Kim F. Storm]

"Robert J. Chassell" <bob@rattlesnake.com> writes:

> This means you have a fast and inexpensive Internet connection.  I
> envy you.

I actually have a fairly expensive, reasonably fast Internet connection.
But it is flat-rate, so it doesn't cost me _extra_ to download a document.

I don't mind finding documentation on the Internet (I'm spoiled, I
know), but of course, I use the local documentation whenever it's
available, and if it's an info file I can read with emacs, that's my
favourite method.

In any case, I don't see any reason to continue this discussion.
Let's write some documentation instead :-)


-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: Gtk patch version 3, part 1

[Richard Stallman]

    The question is real.  The emacs manual needs information about
    how to customize the gtk widgets, yes, but it is not the place to
    document the gtkrc syntax, any more than it is the place to
    document the syntax of X resources.  For this, a cross-reference
    is valuable.

We should handle this case like the X resources case: show precisely
what to do for Emacs.  A cross-reference to the GTK doc for those who
would like more information would be useful to add.

I wrote to the GTK developers asking them to add Info targets to
their makefile.  By and by, there should be an Info file we can
reference.

Re: Gtk patch version 3, part 1

[Alex Schroeder]

Eric Gillespie <epg@pretzelnet.org> writes:

> The question is real.  The emacs manual needs information about
> how to customize the gtk widgets, yes, but it is not the place to
> document the gtkrc syntax, any more than it is the place to
> document the syntax of X resources.  For this, a cross-reference
> is valuable.

But this exactly what we do in the Emacs manual, and I like it!  See
the node Font Specification Options for an example.

Alex.

Re: Texinfo/info: scrolling images (Re: Gtk patch version 3, part 1)

[Stefan Monnier]

> > Having said that, I agree that Texinfo is a superior format for
> > online docs!
> 
> As usual, it depends ;) As it stands, it's somehow related to monospaced
> fonts (info viewer like Emacs must obey hardcoded line breaks) and, more
> important, the info file format still lack image support.

TeXinfo != info


	Stefan

Re: Texinfo/info: scrolling images (Re: Gtk patch version 3, part 1)

[Robert J. Chassell]

   > more important, the info file format still lack image support.

Actually, Info has enjoyed image support from its beginning -- I
remember vividly creating images for Info for the Texinfo manual.  
See File: texinfo, Node: Tree Structuring

The images are built from plain ASCII characters, of course, but they
are there.

Images, even those built from plain ASCII, are a danger.  This is
because Texinfo is designed for a wide variety of output formats, not
only for fast computers and high resolution typset printing.  Texinfo
is designed for listening.

If you drive a car, you are `situationally blind' and should not look
at images in a document, but only listen to it.  If you are
permanently blind, you may be able to feel an image, if you have the
right kind of output equipment, but more likely, you will listen to
it.  

Remember, in its `Emacspeak' variation, GNU Emacs provides a complete
auditory environment for a typical personal computer.  A normal PC
requires no additional cards or parts besides an audio card (which
most modern PCs already have).  Both the `flite' and its Emacs
interface `eflite' are in Debian (and other distributions) and provide
the requisit text-to-voice driver for Emacspeak.

People who have good vision and don't think if using their computers
in theirscars often think images are wonderful.  The use too many of
them.  And they design documents that don't hear well.

-- 
    Robert J. Chassell                         Rattlesnake Enterprises
    http://www.rattlesnake.com                  GnuPG Key ID: 004B4AC8
    http://www.teak.cc                                     bob@gnu.org

Re: Texinfo/info: scrolling images (Re: Gtk patch version 3, part 1)

[Karl Eichwalder]

"Robert J. Chassell" <bob@rattlesnake.com> writes:

> The images are built from plain ASCII characters, of course, but they
> are there.

That's something different.  lilypond authors want to document music
scores and at times I want to talk about graphical interfaces
(screenshots).   ASCII representations of such images are a) different
from the graphical ones and b) highly time consuming to "draw".

At other places, scrolling images is also very important: I'd like to
look at a scan and an OCRed text side by side, that's just 1 example.

> If you drive a car, you are `situationally blind' and should not look
> at images in a document, but only listen to it.

I'm not a car driver anymore ;) OTOH, please note I don't ask you to
drop a feature that helps blind users.  Enhance info in a manner that it
can hold alternative representations of the same contents (ASCII image,
audio variant, graphical image).

> People who have good vision and don't think if using their computers
> in theirscars often think images are wonderful.  The use too many of
> them.  And they design documents that don't hear well.

Yes, point taken.  I'm pretty sure it isn't that difficult to please
_all_ the emacs users.

-- 
ke@suse.de (work) / keichwa@gmx.net (home):              |
http://www.gnu.franken.de/ke/                            |      ,__o
Free Translation Project:                                |    _-\_<,
http://www.iro.umontreal.ca/contrib/po/HTML/             |   (*)/'(*)

Re: Texinfo/info: scrolling images (Re: Gtk patch version 3, part 1)

[Robert J. Chassell]

   "Robert J. Chassell" <bob@rattlesnake.com> writes:

   > The images are built from plain ASCII characters, of course, but they
   > are there.

Karl Eichwalder <keichwa@gmx.net> responds:

   That's something different.  lilypond authors want to document music
   scores and at times I want to talk about graphical interfaces
   (screenshots).   ASCII representations of such images are a) different
   from the graphical ones and b) highly time consuming to "draw".

Yes, the ASCII representations are often different.  In the case of
music, I think you would want to use the `letter' notation that (if I
remember Lilypond rightly) users type in order to input information so
that Lilypond can create the nicely typeset output that it produces.

The design question is:

    to what should you listen when you should not or cannot view the
    typeset output and do not have or should not use a haptic `feel
    pad'?

And yes, the ASCII representations are highly time consuming to
"draw".  This is a major motivation for you to use a format such as
Texinfo that requires such representations.

Without the motivation, sighted people tend to write only for sighted
readers who are not situationally blind.  This is why LaTeX is not
used as the basis for Texinfo.  We tried to make the change more than
a decade ago.  I made many experiments.  

Yes, you can write a LaTeX `deep-representation' file that produces
good Info `surface-expression' output.  But -- and this is the problem
-- often enough, people do not write such files.  Instead, they use
LaTeX' marvelous typesetting capabilities to create papers that
typeset nicely, and which are impossible for someone reading over a
slow connection or who is listening.  XML and DocBook suffer the same
failing.

   At other places, scrolling images is also very important: I'd like to
   look at a scan and an OCRed text side by side, that's just 1 example.

I agree, that is an important action.  At the same time, please
remember that the blind are major users of OCR.  Please design your
system so that you can listen to a scan and to an OCRed text, as well
as look at them.

   > If you drive a car, you are `situationally blind' and should not look
   > at images in a document, but only listen to it.

   I'm not a car driver anymore ;) 

That may be very good (I don't know your personal situation; but it
would be good for the rest of us if fewer people drove cars).
Unfortunately, many other people do drive.  Others work in factories
where they are supposed to be paying attention to their work.

   Enhance info in a manner that it can hold alternative
   representations of the same contents ...

If you really mean Texinfo, this feature has existed for more than a
decade.  What is wrong with the current feature?

If you mean to enhance the GNU Emacs Info reader to provide highly
typeset images for some viewers -- that is a good idea so long as
sighted, non-driving viewers do not write their documentation so that
it cannot be read by a blind person or over a very slow line (even
though I mostly enjoy a reasonably fast connection, sometimes it is
very, very slow).

Info could be made more like W3M mode in Emacs 21.  W3M is a Web
browsing mode in which you can toggle images on or off.  

-- 
    Robert J. Chassell                         Rattlesnake Enterprises
    http://www.rattlesnake.com                  GnuPG Key ID: 004B4AC8
    http://www.teak.cc                                     bob@gnu.org

Re: Texinfo/info: scrolling images

[Karl Eichwalder]

"Robert J. Chassell" <bob@rattlesnake.com> writes:

> Yes, the ASCII representations are often different.  In the case of
> music, I think you would want to use the `letter' notation that (if I
> remember Lilypond rightly) users type in order to input information so
> that Lilypond can create the nicely typeset output that it produces.

Yes, but the goal is to describe and document how the TeX'ed version
will look in the end; thus you want to say something as follows:

    Enter "e" "g" "e" and the score will look (that's my own
    invention--maybe, it's wrong):

    ----------
    ----------
    ----------
    -----o----
    ---o---o--

>    Enhance info in a manner that it can hold alternative
>    representations of the same contents ...
>
> If you really mean Texinfo, this feature has existed for more than a
> decade.  What is wrong with the current feature?

No, I mean the info format.  Like HTML has ALT atributes and DocBook has
<mediaobject> that can hold an object in various formats, info can do
something similar:

    On a graphical device it can display an _graphical_ image and

    -- when running Emacs/info within an xterm -- it can display the
    ASCII representation of the image.

> If you mean to enhance the GNU Emacs Info reader to provide highly
> typeset images for some viewers -- that is a good idea so long as
> sighted, non-driving viewers do not write their documentation so that
> it cannot be read by a blind person or over a very slow line (even
> though I mostly enjoy a reasonably fast connection, sometimes it is
> very, very slow).

Yes, that's what I mean.

> Info could be made more like W3M mode in Emacs 21.  W3M is a Web
> browsing mode in which you can toggle images on or off.  

Exactly :)  Unfortunately, I cannot help with coding.

-- 
ke@suse.de (work) / keichwa@gmx.net (home):              |
http://www.gnu.franken.de/ke/                            |      ,__o
Free Translation Project:                                |    _-\_<,
http://www.iro.umontreal.ca/contrib/po/HTML/             |   (*)/'(*)