Re: Changes to Texinfo DTD

Re: Changes to Texinfo DTD

[Oliver Scholz]

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

> Juri Linkov <juri@jurta.org> wrote
>
>     There are many other arguments for using HTML as Info format.
>
> Before trying to persuade people to change the current Info format,
> please tell us what changes should be made to the current Texinfo DTD.

I was not aware of makeinfo's XML output when I hacked my little
proof-of-concept patch. After Karl Berry mentioned it in private mail,
I had a quick look at it. I think now that it would be a good idea to
use that rather than HTML.

That is because texinfo's HTML output would need to be
changed. Currently it is not easy to parse for an info reader which
would have to identify menus, the beginnings of nodes etc.. And it
does not provide enough of the kind of syntactical information that
only make a change of the format desirable, IMO.

The texinfo XML OTOH would be easy to parse AFAICS and it provides all
syntactical information that I would like to see. And it is already
implemented in makeinfo.

If all other things were equal, HTML would have been nice, because
people were free to choose their suboptimal browser to view the info
files. That might be a small benefit, but it is a benefit. But things
are not equal: the texinfo format is already implemented and up to
the task.  For HTML on the other hand it would be necessary to design
an specify special conventions and to implement those conventions in
makeinfo.

So I have offered to hack the standalone info reader so that it would
support the XML format in the same way that I have chosen in my
patch. But I got not response so far.

[...]
> [Also, how do you view an XML file with a DTD in a manner that looks
> like graphically displayed HTML, as in Mozilla; how do you do the same
> in Emacs?]
[...]

One could write a CSS for texinfo XML, so that at least some browsers,
like Mozilla, could render it.

As for Emacs: I could write a parser and trivial renderer (applying
text-properties) for texinfo XML in on a sunday afternoon.

    Oliver
-- 
Oliver Scholz               28 Brumaire an 212 de la Révolution
Taunusstr. 25               Liberté, Egalité, Fraternité!
60329 Frankfurt a. M.       http://www.jungdemokratenhessen.de
Tel. (069) 97 40 99 42      http://www.jdjl.org

Re: Changes to Texinfo DTD

[Robert J. Chassell]

Oliver Scholz <epameinondas@gmx.de> wrote:

   So I have offered to hack the standalone info reader so that it
   would support the XML format in the same way that I have chosen in
   my patch. But I got not response so far.

Heh... that might be a good idea.  However, I don't think I know of
anyone who uses the standalone Info reader; they all use Emacs Info
instead....  So I cannot give you any useful advice on this.

   [...]
   > [Also, how do you view an XML file with a DTD in a manner that looks
   > like graphically displayed HTML, as in Mozilla; how do you do the same
   > in Emacs?]
   [...]

   One could write a CSS for texinfo XML, so that at least some browsers,
   like Mozilla, could render it.

That would be useful.  I use Galeon (which I presume would also use
the CSS).  The next step would be to persuade the Mozilla/Galeon
developers to make it easy to bind next, prev, up, last,
regexp-search, and spacebar to keystrokes, so you could avoid the
mouse.  As for me, the most vital capability is to be able to regexp
search through a complete document that is in multiple files (i.e.,
the equivalent of the Info-search command), and not attempt to go
outside the document.

   As for Emacs: I could write a parser and trivial renderer (applying
   text-properties) for texinfo XML in on a sunday afternoon.

That would be very useful.  If you provide similar commands to Info,
so similar bindings can be made, people might express all their
Texinfo files in XML with the Texinfo DTD, and try it your renderer,
in place of the current Info.

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

Re: Changes to Texinfo DTD

[Nic Ferrier]

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

>    > [Also, how do you view an XML file with a DTD in a manner that looks
>    > like graphically displayed HTML, as in Mozilla; how do you do the same
>    > in Emacs?]
>    [...]
> 
>    One could write a CSS for texinfo XML, so that at least some browsers,
>    like Mozilla, could render it.
> 
> That would be useful.  I use Galeon (which I presume would also use
> the CSS).  The next step would be to persuade the Mozilla/Galeon
> developers to make it easy to bind next, prev, up, last,
> regexp-search, and spacebar to keystrokes, so you could avoid the
> mouse.  As for me, the most vital capability is to be able to regexp
> search through a complete document that is in multiple files (i.e.,
> the equivalent of the Info-search command), and not attempt to go
> outside the document.

It would be better to provide an XSLT. The XSL could handle things
like keystrokes by associating javascript actions with markup (eg:
nodes).

When I write articles I use an XSLT for transforming the Texinfo
XML. I could adapt that if you like.


Nic

Re: Changes to Texinfo DTD

[Robert J. Chassell]

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

   > .... The next step would be to persuade the Mozilla/Galeon
   > developers to make it easy to bind next, prev, up, last,
   > regexp-search, and spacebar to keystrokes, so you could avoid the
   > mouse. ....

   It would be better to provide an XSLT. The XSL could handle things
   like keystrokes by associating javascript actions with markup (eg:
   nodes).

Does that mean we would not have to ask the Mozilla/Galeon developers
to do anything, but that the XSLT file would provide all that is
needed?  

If so, this sounds like an excellent idea, since it would mean that
the documentation on remote Web sites could be navigated through,
searched, and read nearly as easily as Info documentation locally.

I would especially like to see keystrokes for navigation, like `M-s'
for the equivalent of `Info-search', n, p, u, and spacebar.  Then I
could read a great deal that is remote from my machine and, as a
consequence, from me.

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

Re: Changes to Texinfo DTD

[Nic Ferrier]

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

> "Robert J. Chassell" <bob@rattlesnake.com> writes:
> 
>    > .... The next step would be to persuade the Mozilla/Galeon
>    > developers to make it easy to bind next, prev, up, last,
>    > regexp-search, and spacebar to keystrokes, so you could avoid the
>    > mouse. ....
> 
>    It would be better to provide an XSLT. The XSL could handle things
>    like keystrokes by associating javascript actions with markup (eg:
>    nodes).
> 
> Does that mean we would not have to ask the Mozilla/Galeon developers
> to do anything, but that the XSLT file would provide all that is
> needed?  

Well, enough that it makes adding code to Moz look overkill.

 
> If so, this sounds like an excellent idea, since it would mean that
> the documentation on remote Web sites could be navigated through,
> searched, and read nearly as easily as Info documentation locally.
> 
> I would especially like to see keystrokes for navigation, like `M-s'
> for the equivalent of `Info-search', n, p, u, and spacebar.  Then I
> could read a great deal that is remote from my machine and, as a
> consequence, from me.

You'd be limited on the emulation of emacs keys... I suspect ESC-s
wouldn't work for example, but ALT-S might.

I'm not sure how web standards hold up on modifier keys.


Search is an interesting one... I'm not sure how you'd implement
search. Modern Javascript does have regular expressions... so it
might be possible. XSLT 2.0 has regexs too, as do many XSLT 1.0
implementations out there... so it might be possible with XSLT as
well.

Straight forward would be:

- next/prev
- begin/end 
- index and menu lookups


Nic

Re: Changes to Texinfo DTD

[Oliver Scholz]

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

> Oliver Scholz <epameinondas@gmx.de> wrote:
>
>    So I have offered to hack the standalone info reader so that it
>    would support the XML format in the same way that I have chosen in
>    my patch. But I got not response so far.
>
> Heh... that might be a good idea.  However, I don't think I know of
> anyone who uses the standalone Info reader; they all use Emacs Info
> instead....  So I cannot give you any useful advice on this.

My proposal is to keep the current text/plain info format as an
internal representation in the standalone info reader. 

The reader would then check whether a particular file is in the
text/plain info format or in the XML format. If the former: business
as usual. If the latter, it would convert this XML to plain/text with
the necessary ^_ and the necessary "tags:" section and whatever else
is required *on the fly*. That's the way the patch works that I sent
earlier. Since I won't touch the code of the standalone reader at any
other place, I would need advice mainly on the specification of the
current info format.

IMO this change is the easiest and the least intrusive. I believe that
the transition to a new format would be painless this way. You could
have both the current (then old) info format and the new XML format in
/usr/info and other directories at the same time. The info reader
would just DTRT.

As I said: writing a non-conforming parser for a particular,
machine-generated XML in Emacs Lisp is very, very easy. So info.el
should probably do something slightly more sophisticated with the XML
format and provide more bells&whistles. Or at least we could add the
bells&whistles at a later time. I am not familiar with the code of
info.el and I don't want to deal with it right now.  But I'd offer to
implement any API for dealing with the XML that somebody who wants to
hack info.el would specify.

So. I have stated my cause now. :-)


    Oliver
-- 
Oliver Scholz               30 Brumaire an 212 de la Révolution
Taunusstr. 25               Liberté, Egalité, Fraternité!
60329 Frankfurt a. M.       http://www.jungdemokratenhessen.de
Tel. (069) 97 40 99 42      http://www.jdjl.org

Re: Changes to Texinfo DTD

[Robert J. Chassell]

Oliver Scholz <epameinondas@gmx.de> refers to the standalone Info
reader when he talks about enabling that renderer to determine
whether a document is in Info format or in XML format.

First, it seems to me cleaner to write an XML renderer that can
standalone, and then write separate code to enable the standalone Info
to choose whether to use its current renderer or the new one.

Second, you could write code to enable GNU Emacs to run a standalone
XML renderer, the way it now runs W3M mode -- the advantage of this is
that more people would test the standalone XML renderer than they
would if it only worked outside of Emacs.

Third, ... I don't know whether this is readily possible, but it looks
to me to be a good idea ...  you could add a standalone XML renderer
to Mozilla and related browsers.

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

Re: Changes to Texinfo DTD

[Oliver Scholz]

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

> First, it seems to me cleaner to write an XML renderer that can
> standalone, and then write separate code to enable the standalone Info
> to choose whether to use its current renderer or the new one.

I take that to mean: to write an entirely new program that does the
same job as the current standalone reader, but renders XML. I fail to
see the benefit. I admit that it would be conceptually nicer to have
the program keep the XML document as a DOM-like tree of nodes in
memory rather than as a flat string of characters (for the internal
representation would be the only difference to my proposal). But I do
not see what difference it would make for a user. But maybe I am
missing something.

More importantly: it would be a *lot* of work and you would need
somebody who implements it.  I am certainly not going to write an
entirely new standalone XML browser in C.  But I am willing to
implement my proposal and I am willing to do it now.

> Second, you could write code to enable GNU Emacs to run a standalone
> XML renderer, the way it now runs W3M mode -- the advantage of this is
> that more people would test the standalone XML renderer than they
> would if it only worked outside of Emacs.
[...]

That would also be a *lot* more work and maybe it could even be worse
performance-wise than rendering the XML directly in Elisp. You'd have
the process communication *and* you would still need to parse and
render some ad hoc made markup from the standalone reader.

    Oliver
-- 
Oliver Scholz               30 Brumaire an 212 de la Révolution
Taunusstr. 25               Liberté, Egalité, Fraternité!
60329 Frankfurt a. M.       http://www.jungdemokratenhessen.de
Tel. (069) 97 40 99 42      http://www.jdjl.org

Re: Changes to Texinfo DTD

[Karl Eichwalder]

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

> Third, ... I don't know whether this is readily possible, but it looks
> to me to be a good idea ...  you could add a standalone XML renderer
> to Mozilla and related browsers.

yelp, the GNOME help browser, works directly with XML files conforming
to a DocBook subset - it starts a little bit slow, be warned.

-- 
                                                         |      ,__o
                                                         |    _-\_<,
http://www.gnu.franken.de/ke/                            |   (*)/'(*)

Re: Changes to Texinfo DTD

[Nic Ferrier]

Oliver Scholz <epameinondas@gmx.de> writes:

> "Robert J. Chassell" <bob@rattlesnake.com> writes:
> [...]
> 
> > First, it seems to me cleaner to write an XML renderer that can
> > standalone, and then write separate code to enable the standalone Info
> > to choose whether to use its current renderer or the new one.
> 
> I take that to mean: to write an entirely new program that does the
> same job as the current standalone reader, but renders XML. I fail to
> see the benefit. I admit that it would be conceptually nicer to have
> the program keep the XML document as a DOM-like tree of nodes in
> memory rather than as a flat string of characters (for the internal
> representation would be the only difference to my proposal). But I do
> not see what difference it would make for a user. But maybe I am
> missing something.
> 
> More importantly: it would be a *lot* of work and you would need
> somebody who implements it.  I am certainly not going to write an
> entirely new standalone XML browser in C.  But I am willing to
> implement my proposal and I am willing to do it now.

It wouldn't be a lot of work. It would be trivial with XSLT. There
are basically 2 ways of doing it:


Method 1.
a) patch makeinfo so the XML output can be chunked.

b) prepend an xml-stylesheet processing-instruction to each chunked
   file

c) write an XSLT stylesheet to turn the XML into HTML with navigation
   written in Javascript (so key bindings can be used)

d) serve the files to Mozilla (or IE or any other XSLT aware browser)
   and it will render the XML using the stylesheet

e) For Emacs/W3 we'd have to write an XSLT processing solution, they
   are being worked on I understand. It would be very trivial to write
   one using a command line XSLT tool but see method 2.


Method 2.

a) use a command line XSLT tool such as xsltproc (from the GNOME
   libxml2 project: http://www.xmlsoft.org) to chunk AND style to HTML
   the output of makeinfo --xml.  
   The styling would be as method 1, part c.

b) serve the files, they would be HTML so Emacs/W3 would be able to
   read them without alteration.




> > Second, you could write code to enable GNU Emacs to run a standalone
> > XML renderer, the way it now runs W3M mode -- the advantage of this is
> > that more people would test the standalone XML renderer than they
> > would if it only worked outside of Emacs.
> [...]
> 
> That would also be a *lot* more work and maybe it could even be worse
> performance-wise than rendering the XML directly in Elisp. You'd have
> the process communication *and* you would still need to parse and
> render some ad hoc made markup from the standalone reader.

Nah. Just call out to a command line XSLT engine to turn the XML into
HTML.

This project needs doing anyway because most browsers do it. I'd be
happy to undertake this work on Emacs/W3.



Nic

Re: Changes to Texinfo DTD

[Oliver Scholz]

Nic Ferrier <nferrier@tapsellferrier.co.uk> writes:

> Oliver Scholz <epameinondas@gmx.de> writes:
[...]
>> I take that to mean: to write an entirely new program that does the
>> same job as the current standalone reader, but renders XML. I fail to
>> see the benefit.
[...]
>> More importantly: it would be a *lot* of work and you would need
>> somebody who implements it.

[...]
> It wouldn't be a lot of work. It would be trivial with XSLT. There
> are basically 2 ways of doing it:
>
>
> Method 1.
[...]
> c) write an XSLT stylesheet to turn the XML into HTML with navigation
>    written in Javascript (so key bindings can be used)
>
> d) serve the files to Mozilla (or IE or any other XSLT aware browser)
>    and it will render the XML using the stylesheet
>
> e) For Emacs/W3 we'd have to write an XSLT processing solution, they
>    are being worked on I understand. It would be very trivial to write
>    one using a command line XSLT tool but see method 2.

It seems to me that we are talking about entirely different things. I
wrote under the assumption that a small and lightweight standalone
info reader that works on a console is necessary. It is not that I am
particulary fond of that reader. In fact I have never used it before
this thread started. It is just that I believe that such a
minimalistic reader must exist, because info is the GNU system's
primary help and documentation system. Since everybody in this thread
seemed to agree that getting the standalone console reader to support
a new format would be the hart part, I focused only on this reader.

I think your proposal to enable XSLT aware web browsers to serve as
full info readers is great. But I also think that there has to be at
least one simple, independent solution with minimum requirements that
works under all circumstances, including working on a Linux tty.

If you can make your solution for Emacs work without a significant
performance loss (Emacs/W3 is not the fastest html renderer known to
mankind), then this is fine for me, personally. Though, I don't like
the idea of making C-h i depend on yet another external program,
unless this program ships with the Emacs tarball.


[...]
>> That would also be a *lot* more work and maybe it could even be worse
>> performance-wise than rendering the XML directly in Elisp. You'd have
>> the process communication *and* you would still need to parse and
>> render some ad hoc made markup from the standalone reader.
>
> Nah. Just call out to a command line XSLT engine to turn the XML into
> HTML.
[...]

That's still process communication + rendering.

    Oliver
-- 
Oliver Scholz               30 Brumaire an 212 de la Révolution
Taunusstr. 25               Liberté, Egalité, Fraternité!
60329 Frankfurt a. M.       http://www.jungdemokratenhessen.de
Tel. (069) 97 40 99 42      http://www.jdjl.org

Re: Changes to Texinfo DTD

[Nic Ferrier]

Oliver Scholz <epameinondas@gmx.de> writes:

> It seems to me that we are talking about entirely different things. I
> wrote under the assumption that a small and lightweight standalone
> info reader that works on a console is necessary. It is not that I am
> particulary fond of that reader. In fact I have never used it before
> this thread started. It is just that I believe that such a
> minimalistic reader must exist, because info is the GNU system's
> primary help and documentation system. Since everybody in this thread
> seemed to agree that getting the standalone console reader to support
> a new format would be the hart part, I focused only on this reader.

I am not arguing for a removal of the info reader. I use the info
reader A LOT. Much more than other people in this thread seem to (and
I do mean the info reader, not the emacs info tool).

But why does the info reader have to be adapted to support a new
format?


> If you can make your solution for Emacs work without a significant
> performance loss (Emacs/W3 is not the fastest html renderer known to
> mankind), then this is fine for me, personally. Though, I don't like
> the idea of making C-h i depend on yet another external program,
> unless this program ships with the Emacs tarball.

We don't need to make W3 support XSLT for reading local info files,
only remote ones that you read over the web.

And even then... as Bob was saying, we don't NEED to make Emacs read
the files because there are other solutions for doing it.

I think we're looking at a fairly small problem space here.

 
> > Nah. Just call out to a command line XSLT engine to turn the XML into
> > HTML.
> [...]
> 
> That's still process communication + rendering.

You could say that... but here's the elisp to do the XSL bit:
  
  (let ((x (make-temp-file "xmlout"))
        (n (get-buffer-create "html")))
     (write-region (point-min) (point-max) x)
     (shell-command 
        (concat "xsltproc --html emacsw3-xml-html.xsl "  x)
        n)
     ;; now buffer n contains html so render that...)
 

Nic

Re: Changes to Texinfo DTD

[Robert J. Chassell]

Nic Ferrier <nferrier@tapsellferrier.co.uk> wrote

   Method 1.
   a) patch makeinfo so the XML output can be chunked.
   ....

This sounds the best in the long run.  Some one should be able to take
your code in ten years time and work with it usefully, for some
purpose you never thought of.

   Method 2.
   a) use a command line XSLT tool such as xsltproc (from the GNOME
      libxml2 project: http://www.xmlsoft.org) to chunk AND style to HTML
      the output of makeinfo --xml.  
      The styling would be as method 1, part c.

How is this different from the existing `makeinfo --html' which also
does chunking and styling to HTML?

Without knowing much about `xsltproc', the method scares me.  Does
this method enable me to use keybindings in Mozilla to navigate via
regexp searching within a document that is spread over multiple files?
If so, good and I stop being scared.  Indeed, then the suggestion
becomes very attractive.  But if not, it is a distraction.

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

Re: Changes to Texinfo DTD

[Robert J. Chassell]

Oliver Scholz <epameinondas@gmx.de> wrote

    It seems to me that we are talking about entirely different
    things. I wrote under the assumption that a small and lightweight
    standalone info reader that works on a console is necessary.

Indeed, there are different issues.  One is rendering Texinfo into a
surface expression which a display program can handle as efficiently
as Info.  The second is providing such a display program, or several
of them.

If my understanding is correct, Nic Ferrier is proposing a standard
for an XML format that is a moderate extension of the current XML
format produced by makeinfo.

Also, if I understand correctly, he thinks that the new XML format
will enable existing browsers such as Mozilla to be as efficient as
the current Info mode in Emacs.  And, in addition, with the use of an
appropriate CGI on the Web servers, people will be able to read Info
documents over a slow connection as well as they can read Info on a
local machine.

As Karl Eichwalder <ke@gnu.franken.de> said

    yelp, the GNOME help browser, works directly with XML files
    conforming to a DocBook subset - it starts a little bit slow, be
    warned.

This is good news, since it means that not too much work will be
needed to create a decent renderer for a surface expression of
Texinfo.

Put another way, Info is designed for a fast connection between the
program doing the rendering and the file serving the Info file.  But
HTML is designed for a slow connection between the program doing the
rendering and the Web server providing the HTML file.

As far as I know, the current HTML produced by `makeinfo --html'
permits search/navigation only within a single HTML `page' or file,
not within a document spread over multiple files, as with Info.  So
you need to create HTML documents using the `--no-split' option, which
means as a practical matter, that HTML works quickly only in the same
circumstance as Info, namely that there be a fast connection between
the program doing the rendering and the file server.

The goal is to produce an XML output that not only overcomes the
disadvantages of HTML and Info, but goes ahead of them.

So, to return to Oliver's comment:

    ... I wrote under the assumption that a small and lightweight
    standalone info reader that works on a console is necessary.

Yes, this is necessary, as one of the various display programs that
the new XML could use.  

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

Re: Changes to Texinfo DTD

[Nic Ferrier]

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

> Nic Ferrier <nferrier@tapsellferrier.co.uk> wrote
> 
>    Method 1.
>    a) patch makeinfo so the XML output can be chunked.
>    ....
> 
> This sounds the best in the long run.  Some one should be able to take
> your code in ten years time and work with it usefully, for some
> purpose you never thought of.

Yeah... it seems that:

    makeinfo --xml --split 

should work because one expects it to.

 
>    Method 2.
>    a) use a command line XSLT tool such as xsltproc (from the GNOME
>       libxml2 project: http://www.xmlsoft.org) to chunk AND style to HTML
>       the output of makeinfo --xml.  
>       The styling would be as method 1, part c.
> 
> How is this different from the existing `makeinfo --html' which also
> does chunking and styling to HTML?
> 
> Without knowing much about `xsltproc', the method scares me.  Does
> this method enable me to use keybindings in Mozilla to navigate via
> regexp searching within a document that is spread over multiple files?
> If so, good and I stop being scared.  Indeed, then the suggestion
> becomes very attractive.  But if not, it is a distraction.

It's different because now one can attach javascript to elements on
the page whevever one needs it. The existing HTML doesn't do that,
nor should it because it has an existing purpose.

It's not scary - it's trivial. XSLT is very easy to read and
implement.

The XSLT solution isn't the end. To support regex searches some sort
of webapplication IS needed as well. But XSLT is exactly the best
choice for turning the Texinfo XML into something that would work with
a webapp.

Note that for method 1 and method 2 a webapplication would be needed,
but only for regexp search. All the other tools, navigation, index
lookup, etc... could be solved by javascript within the page.


Nic

Re: Changes to Texinfo DTD

[Nic Ferrier]

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

> Put another way, Info is designed for a fast connection between the
> program doing the rendering and the file serving the Info file.  But
> HTML is designed for a slow connection between the program doing the
> rendering and the Web server providing the HTML file.

I don't really understand this. But maybe I'm not seeing it at the
right level of detail.

No matter, what I'm saying is that we can *easily* make an HTML
representation of Texinfo which is better for people with slow network
connections than the current format.

The representation will operate in a Javascript/XSLT aware browser
and have:

- keyboard navigation
- index term lookup
- node sized downloads

Search will also be included but only with the addition of a web
application (a CGI script probably) held on the same server which is
serving the Texinfo files.

We can do this *because* we have the XML output and don't have to
write complicated HTML rendering code, we can write simply HTML
rendering code with XSLT.


> Oliver said:
>     ... I wrote under the assumption that a small and lightweight
>     standalone info reader that works on a console is necessary.
> 
> Yes, this is necessary, as one of the various display programs that
> the new XML could use.  

You're not saying we have to write a new console info reader for XML
are you? 

If you are saying that: why? The current info reader is fine for
consoles, surely it's okay that it uses a different data format than
XML or HTML?


Nic

Re: Changes to Texinfo DTD

[Richard Stallman]

    e) For Emacs/W3 we'd have to write an XSLT processing solution, they
       are being worked on I understand. It would be very trivial to write
       one using a command line XSLT tool but see method 2.

I can't begin to make sense of that.  How would you propose
that Emacs display one of these XML files?

It can't depend on W3 because W3 is not part of Emacs.

Re: Changes to Texinfo DTD

[Nic Ferrier]

Richard Stallman <rms@gnu.org> writes:

>     e) For Emacs/W3 we'd have to write an XSLT processing solution, they
>        are being worked on I understand. It would be very trivial to write
>        one using a command line XSLT tool but see method 2.
> 
> I can't begin to make sense of that.  How would you propose
> that Emacs display one of these XML files?
> 
> It can't depend on W3 because W3 is not part of Emacs.

One of two ways:

1. use a command line XSLT processor (such as xsltproc, part of
   GNOME's libxsl project) to turn the XML into plain text (or
   specifically marked up text). 

2. write an XSLT processor in Emacs Lisp. This wouldn't be as
   difficult as it sounds and I'm not sure it isn't done already (by
   one of the various XML/Emacs projects going on).


These are only technical possibilites. From an administrative
standpoint the second one is probably the only option since you
wouldn't want to depend the Emacs info reader on xsltproc.


Nic

Re: Changes to Texinfo DTD

[Miles Bader]

On Sat, Nov 22, 2003 at 09:41:39PM +0000, Nic Ferrier wrote:
> 2. write an XSLT processor in Emacs Lisp. This wouldn't be as
>    difficult as it sounds and I'm not sure it isn't done already (by
>    one of the various XML/Emacs projects going on).

The main question in my mind is whether this would be fast enough -- the
current info mechanism, though it has its problems, can display info pages
very quickly.  As a point of contrast, W3 is _very_ slow (I think it would be
completely unsuitable for use in displaying info files).

-Miles
-- 
The secret to creativity is knowing how to hide your sources.
  --Albert Einstein

Re: Changes to Texinfo DTD

[Nic Ferrier]

Miles Bader <miles@gnu.org> 
 writes:

> On Sat, Nov 22, 2003 at 09:41:39PM +0000, Nic Ferrier wrote:
> > 2. write an XSLT processor in Emacs Lisp. This wouldn't be as
> >    difficult as it sounds and I'm not sure it isn't done already (by
> >    one of the various XML/Emacs projects going on).
> 
> The main question in my mind is whether this would be fast enough -- the
> current info mechanism, though it has its problems, can display info pages
> very quickly.  As a point of contrast, W3 is _very_ slow (I think it would be
> completely unsuitable for use in displaying info files).
 
In this response to rms I was not suggesting W3. I was talking about
writing an XSLT processor in emacs lisp. XSLT is pretty quick unless
memory is very limited or the transformation it is given is
particularly complex.


Bob Chassell and I are intending that Emacs/W3 be used as a platform
for viewing our new HTML version of Texinfo. And yes, speed is a
concern.


Nic

Re: Changes to Texinfo DTD

[Stefan Monnier]

> 1. use a command line XSLT processor (such as xsltproc, part of
>    GNOME's libxsl project) to turn the XML into plain text (or
>    specifically marked up text). 

The original reason for discussing such things is that the Info format
has serious limitations w.r.t. additional markup.

"Markup" in this context in the Emacs viewer means "text-properties"
or "overlays", neither of which can be provided directly from a process's
output, so it would just bring us back to square one: which text
representation top use for the markup (either HTML-like or
ANSI-escape-sequences-like, or something else).

I'm not necessarily opposed to using an external tool, but it won't solve
the problem at hand.


        Stefan

Re: Changes to Texinfo DTD

[Nic Ferrier]

Stefan Monnier <monnier@IRO.UMontreal.CA> writes:

> > 1. use a command line XSLT processor (such as xsltproc, part of
> >    GNOME's libxsl project) to turn the XML into plain text (or
> >    specifically marked up text). 
> 
> The original reason for discussing such things is that the Info format
> has serious limitations w.r.t. additional markup.
> 
> "Markup" in this context in the Emacs viewer means "text-properties"
> or "overlays", neither of which can be provided directly from a process's
> output, so it would just bring us back to square one: which text
> representation top use for the markup (either HTML-like or
> ANSI-escape-sequences-like, or something else).
> 
> I'm not necessarily opposed to using an external tool, but it won't solve
> the problem at hand.

I thought I remembered that you could generate saved files with
embedded text properties (they're lisp expressions aren't they?)


Nic

Re: Changes to Texinfo DTD

[Oliver Scholz]

Nic Ferrier <nferrier@tapsellferrier.co.uk> writes:

> Stefan Monnier <monnier@IRO.UMontreal.CA> writes:
>
>> > 1. use a command line XSLT processor (such as xsltproc, part of
>> >    GNOME's libxsl project) to turn the XML into plain text (or
>> >    specifically marked up text). 
>> 
>> The original reason for discussing such things is that the Info format
>> has serious limitations w.r.t. additional markup.
>> 
>> "Markup" in this context in the Emacs viewer means "text-properties"
>> or "overlays", neither of which can be provided directly from a process's
>> output, so it would just bring us back to square one: which text
>> representation top use for the markup (either HTML-like or
>> ANSI-escape-sequences-like, or something else).
>> 
>> I'm not necessarily opposed to using an external tool, but it won't solve
>> the problem at hand.
>
> I thought I remembered that you could generate saved files with
> embedded text properties (they're lisp expressions aren't they?)

Well, the canonical way to save embedded text properties is with M-x
enriched-mode. Or otherwise with the framework provided by format.el
or with (info "(elisp)Saving Properties"). This is technically what I
proposed for Emacs.

But yes, there is a print and read syntax for strings with text
properties: 

(let ((str "#(\"Lirum larum.\" 0 12 
	     (fontified t font-lock-face (variable-pitch :foreground \"Blue\")))"))
  (insert (car (read-from-string str))))

So if it is possible to generate this with XSLT it could be done with
XSLT only. Mostly, at least.

[I'd just like to point out that improving the info file format and
serving info files over the web are two orthogonal issues. It might
be good two use two different approaches to these different goals.
However, if it is feasible to have the same technical solution for
both, then this is fine for me and I'll shut up.]

    Oliver
-- 
Oliver Scholz               3 Frimaire an 212 de la Révolution
Taunusstr. 25               Liberté, Egalité, Fraternité!
60329 Frankfurt a. M.       http://www.jungdemokratenhessen.de
Tel. (069) 97 40 99 42      http://www.jdjl.org

Re: Changes to Texinfo DTD

[Nic Ferrier]

Oliver Scholz <epameinondas@gmx.de> writes:

> [I'd just like to point out that improving the info file format and
> serving info files over the web are two orthogonal issues. It might
> be good two use two different approaches to these different goals.
> However, if it is feasible to have the same technical solution for
> both, then this is fine for me and I'll shut up.]

Absolutely. Bob and I have aimed to solve the web problem, not
improve info in anyway.


Personally, I don't think Info is broken. I use it a lot in
preference to web based tools.


Nic

Re: Changes to Texinfo DTD

[Robert J. Chassell]

Miles Bader <miles@gnu.org> wrote

    The main question in my mind is whether this would be fast enough
    -- the current info mechanism, though it has its problems, can
    display info pages very quickly.

Yes, you are right.  The goal is to provide an alternative to Info
that is as efficient as Info and as fast.

This will help both those who prefer the markup they see in Web
browsers to what they get in Info, and those who use Web browsers,
such as Mozilla, for reading documentation.  (And as a side effect, it
may inspire people to improve W3 mode or another Web browser for
Emacs.)

Right now, it is impossible for any HTML mechanism to be as efficient
as Info, since (as a practical matter) HTML lacks the concept of `one
document in many files'.  HTML runs via a `one document in one file'
schema.  (I am told that in theory a hypertext link can point to one
document that is spread over several files, but I have never seen
this.)

Moreover, a browser, such as Mozilla 1.0, lacks even a regexp search
mechanism for navigating within one page!

However, HTML does have a great advantage over Info: HTML is designed
for the situation in which the rendering computer is separated from the
server by a slow connection.

Info depends on a fast connection between the rendering machine and
the source of the Info file.  Indeed the Info file is often on a disk
on the rendering machine; if not, it is connected via a fast NFS or
similar link.

Here are the two topologies:

Info:
                      fast      rendering       fast
 terminal/display ---  or  ---  computer  --- connection --- Info source
                      slow                      only
                   connection
                                \________ often one computer __________/



HTML:
                                                    fast
                        fast         rendering       or
 terminal/display --- connection --- computer  ---- slow ---- Web server
                                                  connection
  \____________ often one computer __________/

                                     \______ often two computers ______/
                                             connected over the
                                                 Internet


On my current connection, it takes 17 minutes to download the Emacs
Lisp Reference Manual.  There is no way I would wait that long before
beginning to browse the manual remotely.  For remote use, the manual
needs to be divided into smaller files, as Texinfo files are now when
converted to HTML.

Moreover, even with splitting, a search will take too long, unless the
search regexp is sent to the remote site.

I mention search because `Info-search' is still the most efficient way
to navigate through a GNU manual.  String searches through a complete
document (and indices) are very helpful, but simply not good enough.

Consequently, both to help documentation readers who want the kind of
markup they see in a Web browser, and also to help those who want to
read their documentation over the Internet via a slow connection,
current HTML needs to be improved in two ways:

  1. The Texinfo to HTML conversion process needs to ensure that key
     bindings as well as mouse bindings exist for moving from one node
     to another, for index lookups, etc., for a document that is
     spread over several files. 

     Without keybindings, you have to move the mouse, which is fine
     for novices or those who don't mind spending their time doing so,
     but which is not as efficient as simply pressing the spacebar or
     other key, regardless where point is.

     This can be done by providing the document as one or more HTML
     pages, appropriately chunked and formatted and with Javascript
     for the keybindings.  Nothing need be done to the Web server.

  2. The Web server needs a CGI that enables regular expression
     searches/navigation through a single document split among
     several files.  Info has the wonderful `Info-search' command,
     usually bound to `M-s'.  This feature provides the equivalent.

     Since whole documents are often large -- as I said, the Emacs
     Lisp Reference Manual takes me 17 minutes to download -- and HTML
     works by downloading files that are then rendered, the only way
     to provide quick regular expression search and navigation is by
     sending only a search command, such as an `s', to the Web server,
     and having the Web server run the search itself.

     This feature does require adding a module to the Web server.
     This is difficult, since only some Web masters will provide the
     added convenience.  However, it is easy to install CGI scripts on
     Apache.  If the master of the Web server has not installed the
     CGI script, then the Javascript in the Texinfo HTML file tell the
     user that the Web server to which he or she is connected is
     lacking.  And perhaps, eventually, the people who distribute
     Apache will be persuaded to include this module with the others,
     as part of their standard distribution.

I think the far more difficult issue is learning by people who want to
make use of efficient searches and navigation.  Partly, the difference
is preference; but partly the difference is learning.

The kind of efficiency provided by Info is beyond most people's dreams
-- they do not even imagine that an equivalent of `Info-search' could
be useful.  It does not occur them to learn.  Consquently, for many of
the people who want to take advantage of their computer, fundamental
relearning is required.  (For others it is preference, as I said.
Indeed, some people who use Info do not much use `Info-search'.)

On the other hand, Info was not designed for the kind of network we
now have, in which people have their own rendering machines, but
download files from a Web server over a slow connection.  Info was
designed for a network in which the connection between a display or
terminal and the rendering machine may be over a slow connection, but
the connection between the rendering machine and the disk providing
the Info files is fast.

Put another way, both Info and HTML have deficiencies.  The goal here
is make use of HTML's features and add those needed to match Info.

Next, the problem will be to encourage writers to write for all
potential users, not only those who look at documentation on a high
resolution/fast redisplay screen:  to write for people driving cars or
otherwise blind, to write for those working over a really slow
connection, to write for those using limited equipment.

For example, people are going to listen to documents spoken to them
over a cell phone while they drive a car.

Currently, Texinfo files tend to be written for such people, but I see
more and more use of @image without an alternative for those who do
not want images.

But that is a problem for another day.

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

Re: Changes to Texinfo DTD

[Juri Linkov]

Miles Bader <miles@gnu.org> writes:
> On Sat, Nov 22, 2003 at 09:41:39PM +0000, Nic Ferrier wrote:
>> 2. write an XSLT processor in Emacs Lisp. This wouldn't be as
>>    difficult as it sounds and I'm not sure it isn't done already (by
>>    one of the various XML/Emacs projects going on).
>
> The main question in my mind is whether this would be fast enough -- the
> current info mechanism, though it has its problems, can display info pages
> very quickly.  As a point of contrast, W3 is _very_ slow (I think it would be
> completely unsuitable for use in displaying info files).

The current info mechanism is very fast mostly because some formatting
is already done at info files generation time, where the most important
preformatting is the lines filling to 70 columns.  So, if it is
acceptable limitation, the same could be applied to XML solution,
i.e. to generate from Texinfo source such XML files that after
stripping all markup the remaining plain text is already properly
aligned without reformatting.  This will solve the current problem in
Info files, where some lines change their length after hiding a part
of reference.  In XML all additional information can be freely
included into tag attributes without affecting the filling of plain
text.  For example, <a xref="(elisp)Menu Keymaps">Menu Keymaps</a>.

-- 
http://www.jurta.org/emacs/

Re: Changes to Texinfo DTD

[Juri Linkov]

Nic Ferrier <nferrier@tapsellferrier.co.uk> writes:
> Miles Bader <miles@gnu.org> writes:
>> On Sat, Nov 22, 2003 at 09:41:39PM +0000, Nic Ferrier wrote:
>> > 2. write an XSLT processor in Emacs Lisp. This wouldn't be as
>> >    difficult as it sounds and I'm not sure it isn't done already (by
>> >    one of the various XML/Emacs projects going on).
>> 
>> The main question in my mind is whether this would be fast enough -- the
>> current info mechanism, though it has its problems, can display info pages
>> very quickly.  As a point of contrast, W3 is _very_ slow (I think it would be
>> completely unsuitable for use in displaying info files).
>  
> In this response to rms I was not suggesting W3. I was talking about
> writing an XSLT processor in emacs lisp. XSLT is pretty quick unless
> memory is very limited or the transformation it is given is
> particularly complex.

Why do you want to write an XSLT processor in emacs lisp?
The XSL is a poor and ugly copy of Lisp.  I once was enthusiastic
about XSL too, but soon I realized that it's simply a parody of Lisp.
Much better alternative for XML transformation and style formatting
could be the DSSSL, but unfortunately it is not popular now.
So, if you are going to do something in Emacs, please, do it
in Emacs Lisp, not in XSL or JavaScript.

-- 
http://www.jurta.org/emacs/

Re: Changes to Texinfo DTD

[Juri Linkov]

Nic Ferrier <nferrier@tapsellferrier.co.uk> writes:
> "Robert J. Chassell" <bob@rattlesnake.com> writes:
>> Nic Ferrier <nferrier@tapsellferrier.co.uk> wrote
>>    Method 2.
>>    a) use a command line XSLT tool such as xsltproc (from the GNOME
>>       libxml2 project: http://www.xmlsoft.org) to chunk AND style to HTML
>>       the output of makeinfo --xml.  
>>       The styling would be as method 1, part c.
>> 
>> How is this different from the existing `makeinfo --html' which also
>> does chunking and styling to HTML?
>> 
>> Without knowing much about `xsltproc', the method scares me.  Does
>> this method enable me to use keybindings in Mozilla to navigate via
>> regexp searching within a document that is spread over multiple files?
>> If so, good and I stop being scared.  Indeed, then the suggestion
>> becomes very attractive.  But if not, it is a distraction.
>
> It's different because now one can attach javascript to elements on
> the page whevever one needs it. The existing HTML doesn't do that,
> nor should it because it has an existing purpose.

BTW, do you know that HTML files generated from Texinfo files already
have keys for navigation?  The <a> tag has an attribute "accesskey"
which assigns keys to "u" (up), "n" (next), "p" (prev), "[1-5]" (menu).
These keys can be pressed e.g. in Mozilla as M-u, M-n, M-p, M-[1-5]
to navigate to the corresponding HTML node.

There is another useful scheme for navigation in HTML by specifying
a "link" tag in meta section, e.g. <link rel="next" href="next.html" />,
but currently this is not generated in info HTML files.

> The XSLT solution isn't the end. To support regex searches some sort
> of webapplication IS needed as well. But XSLT is exactly the best
> choice for turning the Texinfo XML into something that would work with
> a webapp.

Some indexing programs like swish++ is needed here.  BTW, this was
recently suggested to me, when I asked about searching a mail archive.
I don't know what indexing programs can index info files.

-- 
http://www.jurta.org/emacs/

Re: Changes to Texinfo DTD

[Nic Ferrier]

Juri Linkov <juri@jurta.org> writes:

> BTW, do you know that HTML files generated from Texinfo files already
> have keys for navigation?  The <a> tag has an attribute "accesskey"
> which assigns keys to "u" (up), "n" (next), "p" (prev), "[1-5]" (menu).
> These keys can be pressed e.g. in Mozilla as M-u, M-n, M-p, M-[1-5]
> to navigate to the corresponding HTML node.
> 
> There is another useful scheme for navigation in HTML by specifying
> a "link" tag in meta section, e.g. <link rel="next" href="next.html" />,
> but currently this is not generated in info HTML files.

Yes. I did know that.

But what you can't do is lookup a value in an index, do a secondary
lookup (",") or a search or a follow on search. You can't lookup a
menu item or travel through the document by node (I'm not sure the new
system will allow travel by node though).

In addition those keys, while being good standard HTML can probably
be improved on by using the key event model of the modern web browser
DOM (Document Object Model).


> > The XSLT solution isn't the end. To support regex searches some sort
> > of webapplication IS needed as well. But XSLT is exactly the best
> > choice for turning the Texinfo XML into something that would work with
> > a webapp.
> 
> Some indexing programs like swish++ is needed here.  BTW, this was
> recently suggested to me, when I asked about searching a mail archive.
> I don't know what indexing programs can index info files.

I think it can probably be achieved by grep or awk initially.


Nic

Re: Changes to Texinfo DTD

[Luc Teirlinck]

I am jumping in a thread I have not been following from the beginning
which always carries the danger of completely missing the point, but I
believe that the quote below is talking about alternatives to the
present reformatting of Info files when `Info-hide-note-references' is
t.  If yes, I have a point I want to make to make sure that this
alternative does not make the same mistake as the present
reformatting.  If not, sorry.

Juri Linkov wrote:

   This will solve the current problem in Info files, where some lines
   change their length after hiding a part of reference.  In XML all
   additional information can be freely included into tag attributes
   without affecting the filling of plain text.  For example, <a
   xref="(elisp)Menu Keymaps">Menu Keymaps</a>.

I hope it will also solve the other problem with the current situation
in Emacs with Info-hide-note-references set to t.  Namely, in the
above example, it would just print "Menu Keymaps" without any
indication that this is going to carry you out of the manual you are
reading into the Elisp manual.

Take (elisp)Locales as an example.  The texinfo source contains:

@xref{Locales,,, libc, GNU Libc Manual}, for more information about
locales and locale items.

With Info-hide-note-references set to t this gives:

See Locales for more information about locales and locale items.

"Locales" is the node we are looking at.  So the user thinks:  "This
is silly.  This just offers to carry me to the node I am already
staring at." and does not follow the reference.

With Info-hide-note-references set to nil, we see:

*Note Locales: (libc)Locales, for more information about locales and
locale items.

Oh, it is actually _not_ the node we are staring at, but a node with
exactly the same name in the libc manual!  Now, if we are not sure
what all this "locale" stuff is really about, here is a useful link to
follow.

"*Note Locales: (libc)Locales" is actually OK with me, but other
people consider it too ugly.  That is OK with me too as long as it
does not get replaced with something pretty but misleading.  Replacing
it with "See Locales in the (libc) manual" would be OK.  I am not sure
whether it would be safe to replace it with the "fully pretty":
"See Locales in the GNU Libc Manual", because that refers to the
printed manual. It would look OK in this example, but I do not believe
it is guaranteed to always be OK.

Sincerely,

Luc.

Re: Changes to Texinfo DTD

[Richard Stallman]

    1. use a command line XSLT processor (such as xsltproc, part of
       GNOME's libxsl project) to turn the XML into plain text (or
       specifically marked up text). 

That's much better than making Emacs link with an additional library.

    2. write an XSLT processor in Emacs Lisp. This wouldn't be as
       difficult as it sounds and I'm not sure it isn't done already (by
       one of the various XML/Emacs projects going on).

If someone wants to do it, and it gives good performance, it's an
ok solution.

Re: Changes to Texinfo DTD

[Richard Stallman]

    My proposal is to keep the current text/plain info format as an
    internal representation in the standalone info reader. 

    The reader would then check whether a particular file is in the
    text/plain info format or in the XML format. If the former: business
    as usual. If the latter, it would convert this XML to plain/text with
    the necessary

If this method can be implemented in both the standalone reader and Emacs,
and runs fast enough, then I see no objection.

Re: Changes to Texinfo DTD

[Miles Bader]

On Mon, Nov 24, 2003 at 10:32:45PM +0000, Robert J. Chassell wrote:
> Luc Teirlinck <teirllm@dms.auburn.edu> makes a very good point when he
> says that with `Info-hide-note-references' set to t in Emacs, you can
> lose track of which files hold which nodes.  I hope that Nic's
> implementation does not repeat the mistake.

I know you have a bug up your butt about this, but it has nothing to do with
the discussion at hand -- it's a user interface issue, not an implementation
issue.

If you want to bitch about it again, start a new thread.

-Miles
-- 
Run away!  Run away!

Re: Changes to Texinfo DTD

[Robert J. Chassell]

Luc Teirlinck <teirllm@dms.auburn.edu> makes a very good point when he
says that with `Info-hide-note-references' set to t in Emacs, you can
lose track of which files hold which nodes.  I hope that Nic's
implementation does not repeat the mistake.

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

Re: Changes to Texinfo DTD

[Juri Linkov]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:
> Juri Linkov wrote:
>    This will solve the current problem in Info files, where some lines
>    change their length after hiding a part of reference.  In XML all
>    additional information can be freely included into tag attributes
>    without affecting the filling of plain text.  For example,
>    <a xref="(elisp)Menu Keymaps">Menu Keymaps</a>.
>
> I hope it will also solve the other problem with the current situation
> in Emacs with Info-hide-note-references set to t.  Namely, in the
> above example, it would just print "Menu Keymaps" without any
> indication that this is going to carry you out of the manual you are
> reading into the Elisp manual.

The same is true for web browsers too.  They display only a link title
without URL in the text area.  But when you move the mouse pointer
over a link, the browser displays the URL in the status bar.
Emacs Info currently works in the same way: it puts the help-echo
text property on a reference, so you can see the full address in the
echo area after moving mouse over a reference.

BTW, recently there was a discussion on the emacs-devel list about
displaying help-echo in the echo area after point movements over a
text property.  What was the decision?  This could be useful for Info
buffers too, i.e. when point moves to a reference with help-echo text
property, then Emacs could display the full address in the echo area.

-- 
http://www.jurta.org/emacs/

Re: Changes to Texinfo DTD

[Luc Teirlinck]

Juri Linkov wrote:

   BTW, recently there was a discussion on the emacs-devel list about
   displaying help-echo in the echo area after point movements over a
   text property.  What was the decision?  This could be useful for Info
   buffers too, i.e. when point moves to a reference with help-echo text
   property, then Emacs could display the full address in the echo area.

I just asked Richard whether it was OK to install the new file
"help-at-pt.el" that implements this.  Richard had still some questions
about details concerning help-for-help and the name of a function.

Sincerely,

Luc.

Re: Changes to Texinfo DTD

[Luc Teirlinck]

Yuri Linkov wrote:

   The same is true for web browsers too.  They display only a link title
   without URL in the text area.  But when you move the mouse pointer
   over a link, the browser displays the URL in the status bar.
   Emacs Info currently works in the same way: it puts the help-echo
   text property on a reference, so you can see the full address in the
   echo area after moving mouse over a reference.

Info file names are usually very short, URL's tend to be long.  True,
I can get the full information, but it requires some extra effort.  I
may not take the trouble because I expect it to go to a section of the
manual I am reading, because that is the "normal" situation.  Hence, I
do not worry about it because I have already read it and miss out on
necessary information.  The suggestions in my previous message might
make things too long, but there are other possibilities.  For
instance, one could replace:

*Note Locales: (libc)Locales, for more ...

with:

See Locales (libc) for more ...

instead of with just:

See Locales for more ...

Anyway, if not, then the question is whether your proposed new
implementation will work fine, filling and everything, with all
possible values of Info-hide-note-references.  In that case, everybody
can customize.  (I believe I understood that this thread is talking
about a format that could potentially be used by Emacs, unlike the "A
new online publishing ... " thread.)

Sincerely,

Luc.

Re: Changes to Texinfo DTD

[Juri Linkov]

>    The same is true for web browsers too.  They display only a link title
>    without URL in the text area.  But when you move the mouse pointer
>    over a link, the browser displays the URL in the status bar.
>    Emacs Info currently works in the same way: it puts the help-echo
>    text property on a reference, so you can see the full address in the
>    echo area after moving mouse over a reference.
>
> Info file names are usually very short, URL's tend to be long.  True,
> I can get the full information, but it requires some extra effort.  I
> may not take the trouble because I expect it to go to a section of the
> manual I am reading, because that is the "normal" situation.  Hence, I
> do not worry about it because I have already read it and miss out on
> necessary information.

This looks like a complaint about how all current web browsers work :-)
You don't see in the text area of web browsers whether a link leads
to to same site or not.  Well, some sites (like slashdot.org) adds
the name of external site after a link in the text if link leads outside.
This is actually similar to what you are proposing.

> Anyway, if not, then the question is whether your proposed new
> implementation will work fine, filling and everything, with all
> possible values of Info-hide-note-references.  In that case, everybody
> can customize.  (I believe I understood that this thread is talking
> about a format that could potentially be used by Emacs, unlike the "A
> new online publishing ... " thread.)

I wanted to clarify what is the best way to display references in the
current Info format or XML output of Texinfo without refilling and
without changing line lengths.

-- 
http://www.jurta.org/emacs/

Re: Changes to Texinfo DTD

[Juri Linkov]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:
> Juri Linkov wrote:
>
>    BTW, recently there was a discussion on the emacs-devel list about
>    displaying help-echo in the echo area after point movements over a
>    text property.  What was the decision?  This could be useful for Info
>    buffers too, i.e. when point moves to a reference with help-echo text
>    property, then Emacs could display the full address in the echo area.
>
> I just asked Richard whether it was OK to install the new file
> "help-at-pt.el" that implements this.  Richard had still some questions
> about details concerning help-for-help and the name of a function.

But will this work in Info buffers?  As I remember, there is some
additional text property with a help text such that if point moves
over a character with such property, then a help text is displayed in
the echo area.  Is it so?  This would be useful to display references
to external info manuals in the echo area when references are hidden
in the Info buffer and user navigates between references by keyboard.

-- 
http://www.jurta.org/emacs/

Re: Changes to Texinfo DTD

[Luc Teirlinck]

Yuri Linkov wrote:

   But will this work in Info buffers?  As I remember, there is some
   additional text property with a help text such that if point moves
   over a character with such property, then a help text is displayed in
   the echo area.  Is it so?  This would be useful to display references
   to external info manuals in the echo area when references are hidden
   in the Info buffer and user navigates between references by keyboard.

Essentially, the same text as the one provided on mouse-over by the
help-echo property can get printed on point-over, in the echo area, if
the user sets a timer.  The timer is customizable in various ways.
Without a timer, the text can be printed on demand using "C-h ."  Even
without the timer there are movement functions that move to the next
or previous `help-echo' region and print the help-echo of that region
in the echo area.

So my file is mainly concerned with the help-echo property, although
it provides for a more keyboard oriented alternative kbd-help, in case
help-echo is too exclusively mouse-oriented.

While all of this can be useful when Info-hide-note-references is t, I
do not believe that it is a full substitute for the ability to
customize that variable to nil.

Making invisible text temporarily visible is something different.
There you have reveal-mode, which, if I understand correctly, requires
overlays and does not work well with Info's text properties.  You have
visible-mode which toggles invisibility regardless of whether text or
overlay properties are used.  If one winds up enabling visible-mode
too often in Info however, one probably wants to set
Info-hide-note-references to nil.

Sincerely,

Luc.

Re: Changes to Texinfo DTD

[Luc Teirlinck]

Yuri Linkov wrote:

   I wanted to clarify what is the best way to display references in the
   current Info format or XML output of Texinfo without refilling and
   without changing line lengths.

I do not know XML.  But it would seem to me that keeping
Info-hide-note-references in its present form and having the XML output
already "pre-filled" correctly for all values of the variable might
require passing the value as an extra option to makeinfo --xml.  If
one then would convert Texinfo source files to such pre-filled XML
files as part of the Emacs make process, like they are now converted
to .info files (I do not know whether this is the intention), then one
would have to change Info-hide-note-references from a customizable
variable to an option given to configure (and passed along to 
makeinfo --xml).  One could keep Info-hide-note-references as a
customizable variable by regenerating the pre-filled XML files from
the Texinfo source files as needed, but I do not know whether that
would be fast enough.

Alternatively, Info could consult the value of
Info-hide-note-references and do the filling itself using an XML file
that still contained enough information to respect any @* or @w
commands present in the original Texinfo source.  Or one could
regenerate the pre-filled XML from non pre-filled XML, as needed, in
some other way.  The problem with present refilling attempts with
Info-hide-note-references set to t is not speed, but the fact that the
information contained in @*, @w and the like is not preserved in the
.info files and currently the .info files is all Info has to work
with.  I believe to recall from previous discussions that one of the
benefits of XML would be that it still would contain the XML
equivalents of @*, @w and the like.

Or am I misunderstanding something?  (Again, I do not know XML.)

Sincerely,

Luc.

Re: Changes to Texinfo DTD

[Eli Zaretskii]

> Date: Mon, 24 Nov 2003 10:19:06 -0600 (CST)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> 
> Take (elisp)Locales as an example.  The texinfo source contains:
> 
> @xref{Locales,,, libc, GNU Libc Manual}, for more information about
> locales and locale items.
> 
> With Info-hide-note-references set to t this gives:
> 
> See Locales for more information about locales and locale items.
> 
> "Locales" is the node we are looking at.

We could as well treat this as a case of unfortunate wording in the
ELisp manual.  The above sentence could be modified to solve the
problem at hand:

  The GNU C library manual (@pxref{Locales,,, libc, GNU Libc Manual})
  has more information about locales and locale items.

I notice in passing that a reference to a manual that might not be
installed at all, because it describes a library that is only used by
some platforms, might not be a good idea for purely didactic reasons:
suppose my system doesn't use glibc---how would I learn more about
Locales without the manual being available?

More generally, if the underlying C library is something other than
glibc, I might wonder whether the discussion in the glibc manual is at
all relevant to the treatment of locales I will see on my system.

So the offending sentence seems to be a rather singular case that, as
worded, is troubled to begin with.  We might as well not develop any
theories based on it.

Re: Changes to Texinfo DTD

[Luc Teirlinck]

Eli Zaretskii wrote:

   We could as well treat this as a case of unfortunate wording in the
   ELisp manual.  The above sentence could be modified to solve the
   problem at hand:

     The GNU C library manual (@pxref{Locales,,, libc, GNU Libc Manual})
     has more information about locales and locale items.

That would look terrible in the printed manual with a double nearly
identically worded reference to the GNU Libc manual, once outside
parentheses and once inside parentheses.  The reference in its present
form seems to come out OK in the printed manual, except that maybe
"@xref{Locales,,, libc, GNU Libc Manual}," should be replaced by:
"@xref{Locales,,, libc, The GNU Libc Manual},".  I believe the latter
would look better (in the printed manual).  Anyway, Juri's patch
would solve the problem I complained about.

   I notice in passing that a reference to a manual that might not be
   installed at all, because it describes a library that is only used by
   some platforms, might not be a good idea for purely didactic reasons:
   suppose my system doesn't use glibc---how would I learn more about
   Locales without the manual being available?

How would you learn about Locales without _any_ manual being
referenced?  Of course, the user needs to be alerted that the
reference leads to another manual that may or may not be available
and, if Juri's patch gets installed, they will be.  But why deprive
users that do have the manual installed of this information because
other users do not have the manual installed?  That manual is free
software.  People who do not have it installed can install it.  It is
good to inform them that it is available.

    More generally, if the underlying C library is something other than
    glibc, I might wonder whether the discussion in the glibc manual is at
    all relevant to the treatment of locales I will see on my system.

That manual pays considerable attention to portability.  So my best
guess is that it will be relevant.

Sincerely,

Luc.

Re: Changes to Texinfo DTD

[Eli Zaretskii]

> Date: Tue, 2 Dec 2003 19:47:30 -0600 (CST)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> 
>      The GNU C library manual (@pxref{Locales,,, libc, GNU Libc Manual})
>      has more information about locales and locale items.
> 
> That would look terrible in the printed manual with a double nearly
> identically worded reference to the GNU Libc manual, once outside
> parentheses and once inside parentheses.

That just means my wording should perhaps be improved further, or
maybe we should use @ifinfo and @ifnotinfo to make the text loog good
in both online and hard-copy version.

But I don't think the text I suggested will ``look terrible'', it will
just look a bit awkward.  It is my experience that Texinfo does that
quite a bit: it doesn't make it easy to write cross-references that
look good in all supported formats.  I think the reason for this is
that each format has its own rules for good style, and it isn't easy
to write text that will be compatible with all of them.

> How would you learn about Locales without _any_ manual being
> referenced?

We should first ask ourselves what is there for the user to learn
before she understands what the ELisp manual says in that section.
It's possible that the amount of additional info is small, in which
case we could simply put it into the ELisp manual.  It could also be
that the user doesn't need to know anything else to understand the
ELisp facilities enough to use them.

Do we know what information from the glibc manual is required reading
for the reader of the ELisp manual?

> But why deprive users that do have the manual installed of this
> information because other users do not have the manual installed?

If you mention the manual, the user might think that she must read it
because it contains some crucial information without which it is
impossible to understand the text in point.  I doubt that this is the
case.

>     More generally, if the underlying C library is something other than
>     glibc, I might wonder whether the discussion in the glibc manual is at
>     all relevant to the treatment of locales I will see on my system.
> 
> That manual pays considerable attention to portability.

Portability has nothing to do with this.  The glibc manual can
describe facilities provided only by glibc and not found anywhere
else.  The question is, again, what exactly we want the user to pick
up in the glibc manual.

Re: Changes to Texinfo DTD

[Luc Teirlinck]

   That just means my wording should perhaps be improved further, or
   maybe we should use @ifinfo and @ifnotinfo to make the text loog good
   in both online and hard-copy version.

It would be silly (and impossible) to try to manually rewrite all
references to other manuals in all currently existing .texi files this
way, when the xrefs contain enough information for an Info reader
(actually "makeinfo --xml" reader) to rewrite these sentences
_automatically_ the way you want them rewritten, without requiring any
changes in .texi files and, hence, without any danger of messing up
any other formats.  That was exactly what I proposed in the message
you reacted too.

If you want to do that though, you can not use the Info format.  In
fact, you can not use the Info format to correctly implement a value
of t for Info-hide-note-references.  I do not believe that the main
intent of the Info format ever was to "look cool".  If I understand
correctly, the main intent was that even Info readers with minimal
capabilities should be able to handle it.  That is not very compatible
with making things look "cool", "modern", "beautiful" or whatever you
want to call it.  For me Emacs info does not need to look "cool", it
needs to be easy and efficient to use, but for other people it is
extremely important that it looks as "cool" as possible.  OK with me,
but then it needs to use another format.

If we use XML, we can not only make these and other xrefs come out the
way you want them too, we can do so while filling correctly,
respecting all @*, @w, @verb and the like.  In addition to everything
else people wanted to use XML for in this thread.

Sincerely,

Luc.

Re: Changes to Texinfo DTD

[Luc Teirlinck]

Does anybody have any idea where we stand now with this thread and its
various relatives?  Is the following a reasonable summary?

1. The Info format is "here to stay".  It is intended for readers with
   minimal capabilities and it is important that people can access
   documentation via these readers.

2. Emacs is not a reader with minimal capabilities.  It could use XML
   to make Emacs info look as pretty as it can be, without paying a
   price in terms of functionality.

3. Oliver Scholz has a patch to allow the standalone reader to convert
   XML to Info format "on the fly", so people would only need to have
   the XML files installed to use both Emacs Info and standalone Info.
   Oliver's patch would add some "color" to standalone Info.  (Unless
   these colors would be very customizable, or maybe even if they are,
   please provide a command line option to disable this.  Not
   everybody can read yellow on white, cyan on white or red on black.)

4. Oliver is not volunteering to rewrite info.el to be able to use XML
   himself, although he has offered help, as explained in his earlier
   message.  (I do not know XML and am not volunteering either.)
   Would there be anybody feeling comfortable with this, assuming this
   is really what we wanted to do?
 
5. Emacs will still need to be able to handle .info files, if no XML
   file is available, but certainly if we produce XML files from the
   .texi files, that case becomes marginal enough that we should not
   waste a lot of energy trying to do the impossible by attempting to
   present .info files in "nicer" ways than theoretically possible.

Sincerely,

Luc.

Re: Changes to Texinfo DTD

[Luc Teirlinck]

Eli Zaretskii wrote:

   Do we know what information from the glibc manual is required reading
   for the reader of the ELisp manual?

None.  Some readers _might_ need to know more about locales (hence the
reference), but the _reason_ they would need that knowledge would
definitely not be to understand the Elisp manual.  The same is (or so
I believe) true for all external references in the Elisp manual,
except references to the Emacs manual.  The Emacs manual is a
prerequisite to understanding the Elisp manual, other manuals are not.

Note that this is one more reason why, if a reference refers to another
manual, the reader needs to know that and needs to know which manual.

   If you mention the manual, the user might think that she must read it
   because it contains some crucial information without which it is
   impossible to understand the text in point.  I doubt that this is the
   case.

As I already said, it indeed is not the case.

But (elisp)Locales says as the very last sentence of the note and of
the chapter:

*Note Locales: (libc)Locales, for more information about locales and
locale items.

It says: "for more information", it does not say: "If you want to
understand anything of what you just read".

   Portability has nothing to do with this.

Portability has a lot to do with this.  This is the Elisp manual, not
the Emacs manual.  The author may want his code to not just work, as
efficiently as possible, for his computer and for his locale, but for
other people's as well.

   The question is, again, what exactly we want the user to pick up in
   the glibc manual.

Whichever information the reader happens to need.  The reference means:
If you need to know something we did not tell you above, here is a
reasonable place to search for that information.

Sincerely,

Luc.

Re: Changes to Texinfo DTD

[Eli Zaretskii]

> Date: Wed, 3 Dec 2003 20:53:15 -0600 (CST)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> 
> It would be silly (and impossible) to try to manually rewrite all
> references to other manuals in all currently existing .texi files this
> way

In general, I see nothing silly about making the manual look better.
More specifically, references to other manuals are relatively rare, to
the best of my memory.  And there's no need to rewrite all of them at
once: we could do that whenever we find a problem.

> when the xrefs contain enough information for an Info reader
> (actually "makeinfo --xml" reader) to rewrite these sentences
> _automatically_ the way you want them rewritten

As long as XML didn't replace the current Info format, this option is
a bit academic, IMHO.

Re: Changes to Texinfo DTD

[Eli Zaretskii]

> Date: Wed, 3 Dec 2003 20:54:45 -0600 (CST)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> 
> Does anybody have any idea where we stand now with this thread and its
> various relatives?

IMHO, to make this discussion useful, it needs to be conducted on a
Texinfo forum first and foremost.  This is mostly because the
following item:

> 3. Oliver Scholz has a patch to allow the standalone reader to convert
>    XML to Info format "on the fly", so people would only need to have
>    the XML files installed to use both Emacs Info and standalone Info.
>    Oliver's patch would add some "color" to standalone Info.  (Unless
>    these colors would be very customizable, or maybe even if they are,
>    please provide a command line option to disable this.  Not
>    everybody can read yellow on white, cyan on white or red on black.)

is related to the stand-alone reader, not to Emacs (for which no
equivalent changes are available).

Personally, I think that a move to XML is a good idea, but such a
transition would take a non-trivial period of time, during which we
will need to support installations where some or all of the manuals
are in Info format.

Re: Changes to Texinfo DTD

[Eli Zaretskii]

> Date: Wed, 3 Dec 2003 21:35:56 -0600 (CST)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> 
>    Do we know what information from the glibc manual is required reading
>    for the reader of the ELisp manual?
> 
> None.  Some readers _might_ need to know more about locales (hence the
> reference), but the _reason_ they would need that knowledge would
> definitely not be to understand the Elisp manual.

In that case, we should consider removing the xref or maybe
rewording it so that its importance is minimized.

> Note that this is one more reason why, if a reference refers to another
> manual, the reader needs to know that and needs to know which manual.

I don't need to note this, since I agreed with you in the first place:
that's why I suggested to change the wording to make this point clear.

> But (elisp)Locales says as the very last sentence of the note and of
> the chapter:
> 
> *Note Locales: (libc)Locales, for more information about locales and
> locale items.
> 
> It says: "for more information", it does not say: "If you want to
> understand anything of what you just read".

"@xref{Something}, for more information" is a standard wording, we
use it for many references that are quite important.

>    Portability has nothing to do with this.
> 
> Portability has a lot to do with this.  This is the Elisp manual, not
> the Emacs manual.  The author may want his code to not just work, as
> efficiently as possible, for his computer and for his locale, but for
> other people's as well.

In that case, we should provide information (or a pointer to a source
of such information) that describes the locale issue in a manner that
is independent of any particular implementation.  The glibc manual is
an unlikely place to find such a description, as the glibc
implementation of locale-specific stuff differs in many aspects from
other implementations.

>    The question is, again, what exactly we want the user to pick up in
>    the glibc manual.
> 
> Whichever information the reader happens to need.  The reference means:
> If you need to know something we did not tell you above, here is a
> reasonable place to search for that information.

See above: when we say "see elsewhere for more info", we normally
invite the user to actually go there.

Re: Changes to Texinfo DTD

[Oliver Scholz]

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

[...]
> 3. Oliver Scholz has a patch to allow the standalone reader to convert
>    XML to Info format "on the fly", so people would only need to have
>    the XML files installed to use both Emacs Info and standalone Info.
>    Oliver's patch would add some "color" to standalone Info.  (Unless
>    these colors would be very customizable, or maybe even if they are,
>    please provide a command line option to disable this.  Not
>    everybody can read yellow on white, cyan on white or red on black.)

More precisely: I have an incomplete patch that does this for a
specialised subset of HTML that I invented ad hoc for demonstrational
purposes. It could be extended to support nearly any
pointy-brackets format that's suitable. Thus it should be
straight-forward to make it work with info XML and I have offered to
do that.

> 4. Oliver is not volunteering to rewrite info.el to be able to use XML
>    himself
[...]

Not yet, at least. I do want to make some progress in my pet project
in the next few weeks and months ...

    Oliver
-- 
Oliver Scholz               14 Frimaire an 212 de la Révolution
Taunusstr. 25               Liberté, Egalité, Fraternité!
60329 Frankfurt a. M.       http://www.jungdemokratenhessen.de
Tel. (069) 97 40 99 42      http://www.jdjl.org

Re: Changes to Texinfo DTD

[Oliver Scholz]

Eli Zaretskii <eliz@elta.co.il> writes:

>> Date: Wed, 3 Dec 2003 20:54:45 -0600 (CST)
>> From: Luc Teirlinck <teirllm@dms.auburn.edu>
[...]
> IMHO, to make this discussion useful, it needs to be conducted on a
> Texinfo forum first and foremost.  This is mostly because the
> following item:
>
>> 3. Oliver Scholz has a patch to allow the standalone reader to convert
>>    XML to Info format "on the fly", so people would only need to have
>>    the XML files installed to use both Emacs Info and standalone Info.
>>    Oliver's patch would add some "color" to standalone Info.  (Unless
>>    these colors would be very customizable, or maybe even if they are,
>>    please provide a command line option to disable this.  Not
>>    everybody can read yellow on white, cyan on white or red on black.)
>
> is related to the stand-alone reader, not to Emacs (for which no
> equivalent changes are available).
>
> Personally, I think that a move to XML is a good idea, but such a
> transition would take a non-trivial period of time, during which we
> will need to support installations where some or all of the manuals
> are in Info format.

Now that you mention it ... It is probably a better idea to implement
the feature in Emacs first. 

So people who want it can put XML files into their /usr/local/info
directories on their single-user machines and gain experiences with
it. If it works as advertised, then my proposed compatibility feature
could be added to standalone info afterwards. Maybe this is a more
sensible road-map.

[For testing this extensively, it would be nice if "makeinfo
my-texinfo-source.texi" would produce XML instead of info format,
dependend on the value of some environment variable. Most of my local
info files have been generated by makefiles.]

    Oliver
-- 
Oliver Scholz               14 Frimaire an 212 de la Révolution
Taunusstr. 25               Liberté, Egalité, Fraternité!
60329 Frankfurt a. M.       http://www.jungdemokratenhessen.de
Tel. (069) 97 40 99 42      http://www.jdjl.org

Re: Changes to Texinfo DTD

[Oliver Scholz]

Oliver Scholz <epameinondas@gmx.de> writes:

> Eli Zaretskii <eliz@elta.co.il> writes:
>
[...]
>> Personally, I think that a move to XML is a good idea, but such a
>> transition would take a non-trivial period of time, during which we
>> will need to support installations where some or all of the manuals
>> are in Info format.

In my previous message I forgot to add: I think you are right. Both
the standalone info and `C-h i' should check for each file whether it
is info XML or the current info format and DTRT.

Maybe they should never (i.e. not for a very, very long period of
time) cease to do so.  However efficient XML rendering may become, it
will take more space and more CPU cycles than the current info
format.  Some people still use i486 processors with 8 MB of
core. text/plain info will continue to be a good alternative on low
end machines.

> Now that you mention it ... It is probably a better idea to implement
> the feature in Emacs first. 
[...]


    Oliver
-- 
Oliver Scholz               14 Frimaire an 212 de la Révolution
Taunusstr. 25               Liberté, Egalité, Fraternité!
60329 Frankfurt a. M.       http://www.jungdemokratenhessen.de
Tel. (069) 97 40 99 42      http://www.jdjl.org

Re: Changes to Texinfo DTD

[Robert J. Chassell]

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

   1. The Info format is "here to stay".  It is intended for readers with
      minimal capabilities and it is important that people can access
      documentation via these readers.

Yes.  That is true, but understates Info capabilities:  Info is also,
at the moment, the single most efficient online help mechanism in
existance -- and has been for a generation.  Nic and my goal is to
improve HTML (via XML) to be as efficient or nearly as efficient as
Info was in the 1980s.

(Incidentally, Nic, I still cannot send messages to you via either
nferrier@tapsellferrier.co.uk or nferrier@80.168.156.73.  Please
suggest some other address.)


   2. Emacs is not a reader with minimal capabilities.  It could use XML
      to make Emacs info look as pretty as it can be, without paying a
      price in terms of functionality.

This is mixing the Info renderer with an XML renderer.  It makes more
sense to have them separate.  (It helps keep purposes clearer by
separating the notion of an `info' mechanism for rendering documents,
on line from the `info' format.)  Later, if people want to mix the
two, someone could write a wrapper so that the reader detects whether
the document is in XML format rather than Info format, and, if so,
switches to the XML renderer, or whether it is man page format and, if
so, switches to the man page renderer.

   5. Emacs will still need to be able to handle .info files, if no
      XML file is available, ...

Yes: we currently produce Info, XML, HTML, plain text, and DVI files
directly from the Texinfo files and indirectly PS and PDF and maybe
others.  Info needs to be kept.  Unfortunately, the HTML output does
not equal Info in efficiency.  As I said, Nic and my goal is to
improve it via XML.

(In this case rather than think of the XML output as a `surface
expression' of the Texinfo `deep representation', the XML serves as an
`intermediate representation'.  But clearly, if Emacs gains an XML
renderer, then the XML output from Texinfo acts a surface expression.)

(It is rather interesting to consider the historic transformation of
Emacs from an environment that displayed nearly everything `literally'
to one in which some buffer displays are not literal, but are surface
expressions of a different deep representation.  Nowadays, we even
have a `find-file-literally' command that was not necessary
initially.  But this is off-topic.)

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

Re: Changes to Texinfo DTD

[Eli Zaretskii]

> From: Oliver Scholz <epameinondas@gmx.de>
> Date: Thu, 04 Dec 2003 10:39:27 +0100
> 
> Now that you mention it ... It is probably a better idea to implement
> the feature in Emacs first. 

It's certainly much easier, so I'm in full agreement with you here.

> [For testing this extensively, it would be nice if "makeinfo
> my-texinfo-source.texi" would produce XML instead of info format,
> dependend on the value of some environment variable. Most of my local
> info files have been generated by makefiles.]

One way to do that is to build a hacked version of makeinfo where XML
output is the default.  Then at least you can test this on your
machine(s) with minimal fuss.

Re: Changes to Texinfo DTD

[Karl Berry]

    > [For testing this extensively, it would be nice if "makeinfo
    > my-texinfo-source.texi" would produce XML instead of info format,
    > dependend on the value of some environment variable. 

Ok.  This seems like it should be a very easy change to make.  Alper
(cc-d here) or I will do it for the next release.

(Alper, I'm intentionally leaving out all the reams of context.  It's in
the emacs-devel mailing list archives if you care.)

Re: Changes to Texinfo DTD

[Karl Berry]

    straight-forward to make it work with info XML and I have offered to
    do that.

That sounds like a useful thing to do.  Thanks.

I don't see any problem with doing it in the Info reader as soon as you
like (not that there's any super urgency), without worrying about what
is or isn't happening with Emacs.

Re: Changes to Texinfo DTD

[Karl Berry]

    So people who want it can put XML files into their /usr/local/info

If we start installing XML info files, we need to do better than just
stuff them into one huge /usr/local/info.

I suggest $(infodir)/LL/MANUAL/MANUAL.xml
for instance
/usr/local/info/en/emacs/emacs.xml

1) We want to do a better job of supporting Texinfo documents in
   different languages.
2) We want to allow for including a manual's subsidiary runtime files --
   namely images -- with the manual, so further processors have a chance
   to find them.
3) HTML files could be installed there too.

I'd actually like to install info files in the same way, but that's a
different story.

Perhaps the extension should not be .xml, which is too generic after
all.  .txml?

Re: Changes to Texinfo DTD

[Karl Berry]

Thank you for the concise and clear summary, Luc.

As far as the general issue goes, as I've said before, I completely
agree that building a new Texinfo-XML reader inside Emacs is a better
approach than attempting to remedy the deficiencies of Info format on
bitmapped displayed by kludges on top of the existing Info format.

For example, reformatting paragraphs, hiding note references, printing
different markup in different colors, and all the rest (let alone
putting @ifinfo into the source). 

Although I totally appreciate all the efforts to bring Info into the
world of bitmapped displays, doing it through Info format just does not
seem viable to me.  That is not what Info was designed for, or what it
is good at.

And, I think we all agree that Info format as it currently stands needs
to coexist with whatever new reader/technology is built, in a compatible
way.  There are almost 20 years of Info installations out there, we
cannot render :) them useless in new versions of the software.

Regards,
k

Re: Changes to Texinfo DTD

[Richard Stallman]

    5. Emacs will still need to be able to handle .info files, if no XML
       file is available, but certainly if we produce XML files from the
       .texi files, that case becomes marginal enough that we should not
       waste a lot of energy trying to do the impossible by attempting to
       present .info files in "nicer" ways than theoretically possible.

It is conceivable that this situation will come to pass,
but we should not presume it unless/until it actually happens.

For the moment, Info format is important and is worth improving.

If it happens some day that use of XML makes Info format unimportant, we
can act accordingly.

Re: Changes to Texinfo DTD

[Kim F. Storm]

>     5. Emacs will still need to be able to handle .info files, if no XML
>        file is available, but certainly if we produce XML files from the
>        .texi files, that case becomes marginal enough that we should not
>        waste a lot of energy trying to do the impossible by attempting to
>        present .info files in "nicer" ways than theoretically possible.

In practice, you could also go another route -- and let makeinfo
produce two files, a .info and a .markup file.  The .info file will be
identical to what we have today, while the .markup file will contain a
simple list of "tagging info" for the .info file, which reflects what
@-commands were used to produce each part of the .info file.

something like

@code 341 345
@xref 359 371 378 389    (list each section in the *Note .... output)
@* 459
@page 1033

etc.

i.e. something which a reader (like emacs' info reader) can use
more or less directly to propertize the .info file.


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

Re: Changes to Texinfo DTD

[Karl Berry]

    @code 341 345
    @xref 359 371 378 389    (list each section in the *Note .... output)

I suppose it could be done, but
(1) I see no advantage over the XML output;
(2) It seems significantly harder to read, write, and debug than XML; and
(3) the XML output is already there.  This would require significant new
    effort in makeinfo, without adding commensurate value.

Re: Changes to Texinfo DTD

[Kim F. Storm]

karl@freefriends.org (Karl Berry) writes:

>     @code 341 345
>     @xref 359 371 378 389    (list each section in the *Note .... output)
> 
> I suppose it could be done, but
> (1) I see no advantage over the XML output;

IMO it would be much easier to utilize in emacs' info reader.  It could be
mapped almost 1:1 to suitable text properties, or set boundaries for text
refilling.

> (2) It seems significantly harder to read, write, and debug than XML; and

Are you serious?  

Parsing -- and using -- free-form, inline XML in emacs would be 10
times harder than my simple, "overlay" format.

> (3) the XML output is already there.  This would require significant new
>     effort in makeinfo, without adding commensurate value.

If XML is already there, then why do we discuss this issue at all?

a) isn't this thread about improving XML format?

b) can emacs info reader use the XML format?

c) how much work will it be to make emacs info reader use XML?

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

Re: Changes to Texinfo DTD

[Karl Berry]

    If XML is already there, then why do we discuss this issue at all?

I have no idea.  As far as I can see, the discussion is going in
circles.  We seem to be right back where we started a zillion messages ago.

If someone wants to write a NEW info reader in emacs, based on
makeinfo's xml output (which has existed for a couple of years, and is
being actively maintained), please do.

That is, as I understand it, the whole point -- allow Emacs on a bitmap
display to use nice fonts, rebreak paragraphs, and all that other good
stuff.  To do that, it needs a structure-based representation of the
Texinfo document.

And that is precisely what the XML output gives you, the structure,
unlike the Info (and DVI) output, which is virtually entirely physical.
(HTML is somewhere in between.)  Retrofitting structure into Info format
is going to end up being equivalent to the XML, except MUCH more painful
to define and deal with -- in my opinion, of course.  So I don't want to
spend time doing that.

And, the point is not to "replace" the current character-based info
reader, as rms, bob, I, and many others have said many times.  I can't
imagine why the two cannot peacefully coexist, and users will have the
choice.

Alternatively, Nic and Bob have already advanced a proposal to make Info
work better with web browsers.  So, a better-than-w3 web browser in
Emacs could achieve the same goal.  (By saying this, I know I risk a
rerun of the whole thread ...)

Re: Changes to Texinfo DTD

[Alfred M. Szmidt]

   >     5. Emacs will still need to be able to handle .info files, if
   >        no XML file is available, but certainly if we produce XML
   >        files from the .texi files, that case becomes marginal
   >        enough that we should not waste a lot of energy trying to
   >        do the impossible by attempting to present .info files in
   >        "nicer" ways than theoretically possible.

   In practice, you could also go another route -- and let makeinfo
   produce two files, a .info and a .markup file.  The .info file will
   be identical to what we have today, while the .markup file will
   contain a simple list of "tagging info" for the .info file, which
   reflects what @-commands were used to produce each part of the
   .info file.

If going that route, don't make it a seperate file.  Instead make it
something similar to the "tag table" which exists in info files
already; and call it "markup table". 

Cheers.

Re: Changes to Texinfo DTD

[Eli Zaretskii]

> Date: Sat, 6 Dec 2003 17:11:20 +0100 (MET)
> From: "Alfred M. Szmidt" <ams@kemisten.nu>
> 
>    In practice, you could also go another route -- and let makeinfo
>    produce two files, a .info and a .markup file.  The .info file will
>    be identical to what we have today, while the .markup file will
>    contain a simple list of "tagging info" for the .info file, which
>    reflects what @-commands were used to produce each part of the
>    .info file.
> 
> If going that route, don't make it a seperate file.  Instead make it
> something similar to the "tag table" which exists in info files
> already; and call it "markup table". 

But that would break old versions of the standalone reader, right?
The whole point of Kim's suggestion was to make a change that cannot
possibly break old versions of Info.

Re: Changes to Texinfo DTD

[Alfred M. Szmidt]

   > If going that route, don't make it a seperate file.  Instead make
   > it something similar to the "tag table" which exists in info
   > files already; and call it "markup table".

   But that would break old versions of the standalone reader, right?

I don't think that they should break the standalone read, but I am not
that familiar with the info format.  But I don't think that it should
break anything.


Cheers.

Re: Changes to Texinfo DTD

[Eli Zaretskii]

> Date: Tue, 9 Dec 2003 17:47:43 +0100 (MET)
> From: "Alfred M. Szmidt" <ams@kemisten.nu>
> 
>    > If going that route, don't make it a seperate file.  Instead make
>    > it something similar to the "tag table" which exists in info
>    > files already; and call it "markup table".
> 
>    But that would break old versions of the standalone reader, right?
> 
> I don't think that they should break the standalone read, but I am not
> that familiar with the info format.

I think it will break the standalone reader.  The way the code that
reads the tag tables is written is not very robust to changes in that
part of the Info file.

Re: Changes to Texinfo DTD

[Alper Ersoy]

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

Hi,

Karl Berry:
>     > [For testing this extensively, it would be nice if "makeinfo
>     > my-texinfo-source.texi" would produce XML instead of info format,
>     > dependend on the value of some environment variable. 

I just committed this one.  Patch attached to this mail.

-- 
Alper Ersoy

[-- Attachment #2: envvar.diff --]
[-- Type: text/plain, Size: 1088 bytes --]

Index: makeinfo/makeinfo.c
===================================================================
RCS file: /cvsroot/texinfo/texinfo/makeinfo/makeinfo.c,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -p -r1.2 -r1.3
--- makeinfo/makeinfo.c	2003/12/13 11:00:42	1.2
+++ makeinfo/makeinfo.c	2003/12/13 11:11:56	1.3
@@ -1,5 +1,5 @@
 /* makeinfo -- convert Texinfo source into other formats.
-   $Id: makeinfo.c,v 1.2 2003/12/13 11:00:42 dirt Exp $
+   $Id: makeinfo.c,v 1.3 2003/12/13 11:11:56 dirt Exp $
 
    Copyright (C) 1987, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
    2000, 2001, 2002, 2003 Free Software Foundation, Inc.
@@ -739,6 +739,17 @@ For more information about these matters
           usage (1);
           break;
         }
+    }
+
+  /* If TEXINFO_XML_OUTPUT envvar is set, we default to XML output.  */
+  if (getenv ("TEXINFO_XML_OUTPUT") != NULL
+      && !STREQ (getenv ("TEXINFO_XML_OUTPUT"), "0"))
+    {
+      splitting = 0;
+      html = 0;
+      docbook = 0;
+      xml = 1;
+      process_xml = 1;
     }
 
   if (macro_expansion_output_stream)

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

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