terminal escapes in Info files?

terminal escapes in Info files?

[Karl Berry]

Dear Emacs developers,

Alper Ersoy (GTK developer, cc'd here) suggested to me that we enhance
Info format by allowing terminal escapes.  For example, @strong{this is
bold} in the Texinfo source could then end up getting displayed in
standout mode.

I can imagine two ways to implement this:
1) write ANSI terminal escape codes directly in the Info file.  (Even on
non-ANSI terminals, if there are any left, these could be translated to
appropriate termcap sequence.)

2) use the mechanism we created for @image to write a generic command in
the Info file, something like
      ^H^[display bold^H^]this is bold^H^[end display^H^]

In either case, the escapes would only be enabled with an option to
makeinfo for now, to provide for a phase-in period.

So here are my questions:
- what do you-all think of the idea in general?

- is one of (1) or (2) significantly easier to implement in Emacs?
  (2) is already implemented in standalone Info, via the --raw-escapes
  option, but this is not a determining factor in my mind.
  
  I know that Emacs's terminal-mode will interpret terminal escapes, but
  I don't know how easily that (or any other such support) can be
  integrated into info read.

- would anyone like to volunteer to implement this for Emacs :)?
  Neither Alper nor I can do it.  We can handle the makeinfo/standalone
  info changes, of course.

Thanks,
karl


P.S. Here are some references, FWIW:

- A list of escapes:
  http://www.isthe.com/chongo/tech/comp/ansi_escapes.html

- Documentation on using escapes in bash prompts:
  http://www.linux.org/docs/ldp/howto/Bash-Prompt-HOWTO/c341.html

- ANSI support in various terminals:
  http://search.cpan.org/~rra/ANSIColor-1.07/ANSIColor.pm#NOTES

Re: terminal escapes in Info files?

[Simon Josefsson]

karl@freefriends.org (Karl Berry) writes:

> 1) write ANSI terminal escape codes directly in the Info file.  (Even on
> non-ANSI terminals, if there are any left, these could be translated to
> appropriate termcap sequence.)
...
> - is one of (1) or (2) significantly easier to implement in Emacs?

Rendering ANSI escape sequences in e-mail was recently proposed for
Gnus, and thanks to ansi-color.el it is easy to do: just call
ansi-color-apply-on-region from ansi-color.el.  You only need to make
sure the ESC sequence is not destroyed until it reach the decoding
code, of course.

(autoload 'ansi-color-apply-on-region "ansi-color")

(defun article-treat-ansi-sequences ()
  "Translate ANSI SGR control sequences into overlays or extents."
  (interactive)
  (save-excursion
    (when (article-goto-body)
      (let ((buffer-read-only nil))
	(ansi-color-apply-on-region (point) (point-max))))))

PS.  Alex, what do you think about the following?  Those functions are
documented in the top-level comment, and appear to be basic API entry
points for the ansi-color.el library, so it might be useful to
autoload them.  I don't know if adding autoload cookies here and there
is considered polluting though.

--- ansi-color.el.~1.14.~	2003-10-07 19:16:00.000000000 +0200
+++ ansi-color.el	2003-10-26 13:37:37.000000000 +0100
@@ -1,6 +1,6 @@
 ;;; ansi-color.el --- translate ANSI escape sequences into faces
 
-;; Copyright (C) 1999, 2000, 2001  Free Software Foundation, Inc.
+;; Copyright (C) 1999, 2000, 2001, 2003  Free Software Foundation, Inc.
 
 ;; Author: Alex Schroeder <alex@gnu.org>
 ;; Maintainer: Alex Schroeder <alex@gnu.org>
@@ -285,6 +285,7 @@
 escape sequence.")
 (make-variable-buffer-local 'ansi-color-context)
 
+;;;###autoload
 (defun ansi-color-filter-apply (string)
   "Filter out all SGR control sequences from STRING.
 
@@ -315,6 +316,7 @@
 	(setq ansi-color-context nil)))
     result))
 
+;;;###autoload
 (defun ansi-color-apply (string)
   "Translates SGR control sequences into text-properties.
 
@@ -398,6 +400,7 @@
 	(setq ansi-color-context-region (list nil (match-beginning 0)))
       (setq ansi-color-context-region nil)))))
 
+;;;###autoload
 (defun ansi-color-apply-on-region (begin end)
   "Translates SGR control sequences into overlays or extents.

Re: terminal escapes in Info files?

[Alex Schroeder]

Simon Josefsson <jas@extundo.com> writes:

> PS.  Alex, what do you think about the following?  Those functions are
> documented in the top-level comment, and appear to be basic API entry
> points for the ansi-color.el library, so it might be useful to
> autoload them.  I don't know if adding autoload cookies here and there
> is considered polluting though.

I don't mind more autoloads, but if you write code that you *know*
will use ansi-color, then the right thing would be to require the
library.  Per default, autoload cookies would only be used for a)
interactive stuff and b) very common stuff.  I don't think ansi-color
is that commen, yet.

As to applying patches right now: With this huge ansi-code.el file I
received, it seems like a major rewrite of ansi-color.el will
be likely to happen.  Any volunteers to take over maintainership?  :)

Alex.
-- 
http://www.emacswiki.org/alex/
There is no substitute for experience.

Re: terminal escapes in Info files?

[Richard Stallman]

if we want to add font markup to info fmt, let's not use something as
ugly as terminal escape squences.  please design something clean!

Re: terminal escapes in Info files?

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Date: Mon, 27 Oct 2003 02:02:29 -0500
> 
> if we want to add font markup to info fmt, let's not use something as
> ugly as terminal escape squences.  please design something clean!

How about using what Enriched-Text mode uses in Emacs?  See
etc/enriched.doc in the Emacs distro.

Re: terminal escapes in Info files?

[Karl Berry]

    > if we want to add font markup to info fmt, let's not use something as
    > ugly as terminal escape squences.  please design something clean!

Since Info is inherently limited to what can be displayed on a terminal,
it seems like ANSI escape sequences are as reasonable specification of
the capabilities as anything else?  Easy to implement, too.  Admittedly
the ESC [ blah blah sequences are ugly, though.

    How about using what Enriched-Text mode uses in Emacs?  See
    etc/enriched.doc in the Emacs distro.

That is indeed a lot cleaner (also quite a bit more verbose :).  Thanks
for mentioning it, I wasn't aware of it.

It seems using this would imply a new non-backward-compatible output
format, though, since every literal < needs to be escaped in enriched
format, and existing info readers don't know how to do that.

Using the ugly terminal escape sequences, on the other hand, is
backward-compatible because I'm sure that no real document has literal
terminal escape sequences (Texinfo hasn't had @ctrl for years ...).

Hmm.  As always, it seems there is no easy answer.

Thanks,
k

Re: terminal escapes in Info files?

[Alper Ersoy]

Karl Berry:
>     How about using what Enriched-Text mode uses in Emacs?  See
>     etc/enriched.doc in the Emacs distro.

> That is indeed a lot cleaner (also quite a bit more verbose :).  Thanks
> for mentioning it, I wasn't aware of it.

I think we can summarize the possible directions in two groups:

  1) Older versions friendly,
  2) Future versions friendly.

(1) is using ANSI escapes directly in Info files.  The benefit is,
these files will still be displayed correctly by older versions of
info when -R option is given (though I'm not sure about emacs.) Also
no further processing is necessary in info.  Minimal set of changes,
most will be in makeinfo.

The downside is, GUI browsers will be limited severely by an
inexpansible markup on what can be done when rendering.  For example
two elements having the same ANSI escapes (@var{} and @env{} are good
candidates) may become indistinguishable even though there's enough
room in the display environment to associate different styles with
these elements.  Also ANSI is a frozen specification, so we may hit
its limits pretty soon.

(2) is using a specialized markup.  The benefit is of course Info
files will take advantage of the medium they are presented in to its
maximum, provided that the browser is aware of this markup.

The downside is, Info becomes an intermediate format rather than
a final one, always asking for an additional step in the browsers.
Display will be totally screwed in older versions[1].

So, the decision really is on the part of Info history we can discard
rather than the markup format.  The bad thing about standards is it's
very hard to break them ;)

Thanks,

[1] We must give a visual clue about this to avoid possible
frustration.  Perhaps something like the following at the top
of each node?

  ^H^[ignore]
    Your browser relies on an obsolete Info specification.
    See *note bla bla::.
  ^H^[/ignore] (or some other markup)

And a hidden DON'T PANIC! "bla bla" node that gives information about
where to find new versions of browsers.  Compliant browsers will
conceal this text and also hide "bla bla" node from tab completions,
next/prev commands, etc.  completely.  But I digress.

-- 
Alper Ersoy

Re: terminal escapes in Info files?

[Oliver Scholz]

Alper Ersoy <dirt@gtk.org> writes:

[...]
> (2) is using a specialized markup.  The benefit is of course Info
> files will take advantage of the medium they are presented in to its
> maximum, provided that the browser is aware of this markup.

Most notably the markup could be syntactical rather than specifying
the colours to use. I *hate* it, if a document tells me the best
colour for me to read a certain syntactic element. Let the document
specify the syntactical element and let me customize the colour.

However, I would be nice at least, if the info format and the Emacs
info reader would distinguish `example' and `code' and the like from
the rest of the text. So that I can use a fixed width font for those
parts and a proportional font for the rest.

Another old wish of mine is that the info format could specify the
type of code, for example (I am using an XML-like notation here,
because I am not familiar with the info file format):

<code type="lisp">
   (defun bar (a &optional b &rest c)
     (list a b c))
</code>

Then the info reader in Emacs could even fontify the code.
[There's probably a better choice than XML-like markup, but you get
the idea. I guess it should be done in a way that a tty reader may
simply strip the markup.]

    Oliver
-- 
Oliver Scholz               7 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: terminal escapes in Info files?

[Stefan Monnier]

>> How about using what Enriched-Text mode uses in Emacs?  See
>> etc/enriched.doc in the Emacs distro.

Why not HTML ?  There's already an HTML backend in makeinfo, so no
change is needed there.  Also it has the advantage of providing much
more markup so that text-reflowing is possible.

Maybe the current HTML output is not appropriate for an Info-like
reader, so maybe some touch up will be needed, but I think it's
not a bad direction to go.  At least, it's no worse than the idea
of introducing yet-another-markup.

Of course, a direction I'd even prefer is some way to make it possible to
use the TeXinfo file(s) directly (probably with some form of caching for
things like the indices that would be generated on the fly).


        Stefan

Re: terminal escapes in Info files?

[Karl Berry]

    Of course, a direction I'd even prefer is some way to make it possible to
    use the TeXinfo file(s) directly

The problem with this approach is that then Emacs has to know about
every change to the Texinfo source language.  That does not seem like a
good idea.  New commands could not be added to Texinfo without impacting
Info readers, in that case.  rms intentionally designed Texinfo so that
this would not happen.

In the present situation, info readers generally don't have to know or
care what the source commands are and when they change.  I've added
probably 20+ commands without impacting any reader and without any
compatibility issues.  (Occasionally there are commands that do have
compatibility issues, such as @anchor and the new @image support, but
these have been the exception.)

If I'm missing something here, please let me know ...

Re: terminal escapes in Info files?

[Karl Berry]

    Why not HTML ?  There's already an HTML backend in makeinfo, so no
    change is needed there.  

HTML is possible, but people who want that can already use it, right?
The question is how or whether to improve Info format.

Re: terminal escapes in Info files?

[Stefan Monnier]

>     Why not HTML ?  There's already an HTML backend in makeinfo, so no
>     change is needed there.
> HTML is possible, but people who want that can already use it, right?
> The question is how or whether to improve Info format.

Sorry, I thought the question was how to improve the `info' program
and the `M-x info' command.

Why do people want to improve the Info format, exactly?


        Stefan

Re: terminal escapes in Info files?

[Eli Zaretskii]

> From: Stefan Monnier <monnier@IRO.UMontreal.CA>
> Date: 28 Oct 2003 11:59:50 -0500
> 
> Sorry, I thought the question was how to improve the `info' program
> and the `M-x info' command.
> 
> Why do people want to improve the Info format, exactly?

Because it allows features such as index search that are not
available in HTML, and yet doesn't support colors, bold/italics, and
other text attributes that existing text-mode terminals can display.

For details, see this message (which started this thread):

  http://mail.gnu.org/archive/html/emacs-devel/2003-10/msg00621.html

Re: terminal escapes in Info files?

[Karl Berry]

    Sorry, I thought the question was how to improve the `info' program
    and the `M-x info' command.

Yes, sure.  What are you saying?

If you're proposing that, say, info become an alias for lynx and
M-x info become an alias for w3-whatever, well, fine, but that doesn't
really address the issue.

    Why do people want to improve the Info format, exactly?

Because, believe it or not, some people still use it, there's a lot of
history there, and just eradicating Info and replacing it with HTML
would not go over well.

    Eliz>features such as index search that are not
    available in HTML

Well, since we're hypothetically talking about M-x info, I could imagine
it reading the HTML from a Texinfo document and knowing about the index, etc.

    yet doesn't support colors, bold/italics, and
    other text attributes that existing text-mode terminals can display.

<font color="red">
<b>
...
(Whether Emacs is capable of using any of that stuff on a text terminal,
I don't know.)

Re: terminal escapes in Info files?

[Stefan Monnier]

> Because it allows features such as index search that are not
> available in HTML,

Huh?  Why don't the HTML pages generated by makeinfo allow index search?
>From what I can tell they include indices just fine, exactly like
the Info format version.  It can be even better because the hyperref
to the index node can be annotated to indicate it's an index node whereas
the Info format relies on the name used in the menu to tell the
difference between an index node and a non-index node, which
makes it inadequate for non-english text.

Existing HTML browsers suck, but that doesn't mean we can't use the HTML
markup with a specially designed Info viewer (which might not even need to
understand 100% of HTML).

> and yet doesn't support colors, bold/italics, and
> other text attributes that existing text-mode terminals can display.

> For details, see this message (which started this thread):

>   http://mail.gnu.org/archive/html/emacs-devel/2003-10/msg00621.html

This does not answer my question: why enhance the Info format
rather than change the readers (to use the HTML output of makeinfo
rather than the Info output) ?
I don't know about other Info browsers, but Emacs's M-x info has been
recently showing signs of bumping into limits of the Info format which
would be lifted if it used the HTML format instead.


        Stefan

Re: terminal escapes in Info files?

[Stefan Monnier]

> Because, believe it or not, some people still use it,

Of course I use it everyday.

> there's a lot of history there, and just eradicating Info and replacing it
> with HTML would not go over well.

But by switching to something like enriched-mode, we're heading straight
down that path and it isn't hard to see that sooner or later we'd want
more than enriched-mode and ...

I guess the question is: how much work would it require to take
the subset of HTML generated by makeinfo and render it (both
in M-x info and in the info program) ?


        Stefan

Re: terminal escapes in Info files?

[Karl Berry]

    >From what I can tell they include indices just fine, 

Eli is talking about the i command (which a lot of people like).  You
can't type i into a general html browser and expect to get completion on
index entries.

Re: terminal escapes in Info files?

[Karl Berry]

    But by switching to something like enriched-mode, 

After a bit thought, I think we can't "switch" to enriched mode,
exactly, because of the compatibility problem.  We could write enriched
text as a new output format, and maybe in five years or so make it the
default.

    I guess the question is: how much work would it require to take
    the subset of HTML generated by makeinfo and render it (both
    in M-x info and in the info program) ?

As for the info program goes, it would be tantamount to writing a new
program.  I guess some of the screen display stuff could be reused.  But
in any case, I definitely wouldn't bother doing this.  Instead, I'd just
tell people to use lynx or emacs-w3 or whatever.  I've never really seen
the point of standalone info in the first place, as I've mentioned before.
But some people like it, so fine.

Also, makeinfo's html output is very very far from ideal.  (texi2html
does a better job, sadly.)  So it wouldn't be a good design to implement
only the html being output now.  I suspect it would end up needing to be
close to a full-fledged html interpreter, for the same reasons that you
surmise enriched text would eventually not be enough.

    why enhance the Info format rather than change the readers (to use
    the HTML output of makeinfo rather than the Info output) ?

1) Because that is a huge change with many ramifications.
2) Because anyone who wants to can already do that.  If you or anyone
   want to write or improve HTML readers for makeinfo's html output, great. 
   That can be done independently of changing existing Info files.
3) [the main point] Because Info is terminal-based.  Therefore, it makes
   sense to add capabilities to Info format which can be expressed on
   terminals -- namely, standard terminal escape sequences.  This is
   where we came in.

Inventing an entirely new output format, or using html as you suggest,
may well be a worthwhile goal, but it is very long term and will take a
lot of effort.

By contrast, getting the principal two existing Info readers to
understand ANSI escape sequences is very little work by comparison, has
no compatibility issues, and could immediately improve the info-browsing
experience.

One more msg coming up ...

Re: terminal escapes in Info files?

[Karl Berry]

rms: I am actually coming to believe that using the raw terminal escape
sequences is as clean as anything else in this particular limited
context.  We specifically want to support what terminals can support.
Aren't the ANSI escape sequences as reasonable a way of specifying that
as anything?

I don't see any particular advantage to writing ^H^[bold^H^] (or <bold>
or whatever) instead of ^[[3m, and the implementation in both info and
M-x info gets much more complex if we introduce a layer of indirection,
which all it really amounts to.

This discussion is telling me that we may want a better output format in
general than Info, but any significant/large extensions are hard to mark
and turn Info into something other than what it was designed to be:
output on a terminal.  So, as far as improving Info itself goes in the
short term, this seems as good as anything.

What do you think?

Re: terminal escapes in Info files?

[Eli Zaretskii]

> From: Stefan Monnier <monnier@IRO.UMontreal.CA>
> Date: 28 Oct 2003 12:56:31 -0500
> 
> > Because it allows features such as index search that are not
> > available in HTML,
> 
> Huh?  Why don't the HTML pages generated by makeinfo allow index search?

Because HTML browsers don't know about Info indices.

> Existing HTML browsers suck, but that doesn't mean we can't use the HTML
> markup with a specially designed Info viewer (which might not even need to
> understand 100% of HTML).

We were talking about existing readers, perhaps modified a bit, not
about inventing a new reader.

> This does not answer my question: why enhance the Info format
> rather than change the readers (to use the HTML output of makeinfo
> rather than the Info output) ?

Because, as Karl pointed out, we already have that.

Re: terminal escapes in Info files?

[Stefan Monnier]

> By contrast, getting the principal two existing Info readers to
> understand ANSI escape sequences is very little work by comparison, has
> no compatibility issues, and could immediately improve the info-browsing
> experience.

That makes sense.  My question was more relevant in the case where we'd
switch to enriched-text.


        Stefan

Re: terminal escapes in Info files?

[Miles Bader]

On Tue, Oct 28, 2003 at 03:06:04PM -0500, Karl Berry wrote:
> But
> in any case, I definitely wouldn't bother doing this.  Instead, I'd just
> tell people to use lynx or emacs-w3 or whatever.  I've never really seen
> the point of standalone info in the first place, as I've mentioned before.
> But some people like it, so fine.

The reasons seem obvious, because the info program is optimized for browsing
info files -- it includes things like index access, full-document search
(without requiring the whole document to be on one node), etc.

Even if we suddenly switched over to using html (or something) for info, we
_shouldn't_ just use the current html backend, we should use certain
conventions to encode extra information that the html-info reader can use to
provide the various extra functions that make info so useful.  IOW, html is
the low-level formatting language used, but that doesn't mean that it's `just
html'; it might be readable by a normal web browser, but you'd lose the extra
functionality in that case.

[Of course, it could be that the quickest way to make an `html-info' program
would be to enhance an existing web browser like lynx (well except that lynx
is fairly crappy, maybe use `links' instead).]

-Miles
-- 
P.S.  All information contained in the above letter is false,
      for reasons of military security.

Re: terminal escapes in Info files?

[Oliver Scholz]

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

>> Because, believe it or not, some people still use it,
>
> Of course I use it everyday.
>
>> there's a lot of history there, and just eradicating Info and replacing it
>> with HTML would not go over well.
>
> But by switching to something like enriched-mode, we're heading straight
> down that path and it isn't hard to see that sooner or later we'd want
> more than enriched-mode and ...
>
> I guess the question is: how much work would it require to take
> the subset of HTML generated by makeinfo and render it (both
> in M-x info and in the info program) ?
[...]

Just my 0.02 EUR:

The HTML for C-h i would not need to be “real” HTML, just something
which would look like HTML to a browser. What I mean is: It could be
like the text/enriched format (whitespace being significant, so that
you get a nice plain text when you just strip the markup), but with
tags borrowed from HTML:

<!-- [info file] -->
<html>
<h1>Defining Functions</h1>

<p>   We usually give a name to a function when it is first created.  This
is called "defining a function", and it is done with the `defun'
special form.</p>

<p> - Special Form: <b>defun</b> name argument-list body-forms
     `defun' is the usual way to define new Lisp functions.  It defines
     the symbol NAME as a function that looks like this:</p>

<code class="example"><pre>     
          (lambda ARGUMENT-LIST . BODY-FORMS)
</pre></code>

[...]

<code class="lisp"><pre>
          (defun capitalize-backwards ()
            "Upcase the last letter of a word."
            (interactive)
            (backward-word 1)
            (forward-word 1)
            (backward-char 1)
            (capitalize-word 1))
</pre></code>

[...]
</html>


In that case it should be simple to use either format.el or
`write-region-annotate-functions' to strip the markup and put faces or
other text properties on the text. Proof of concept (works with the
example above):


(defconst info-translations
  '((face (Info-title-1-face "h1")
	  (variable-pitch "p")
	  (bold "b"))
    (nil (nil "code"))
    (nil (nil "pre"))))

(defun info-next-annotation ()
  (let ((found nil))
    (while (and (not found)
		(search-forward "<" nil t))
      (backward-char 1)
      (cond ((looking-at "</\\([[:alnum:]]+\\)>")
	     (setq found (list (match-beginning 0)
			       (match-end 0)
			       (match-string 1)
			       nil)))
	    ((looking-at "<\\([[:alnum:]]+\\)\\(?:.*?\\)>")
	     (setq found (list (match-beginning 0)
			       (match-end 0)
			       (match-string 1)
			       t)))
	    ((looking-at "<!--")
	     (let ((beg (point)))
	       (when (search-forward "-->" nil t)
		 (skip-chars-forward "\n")
		 (delete-region beg (point)))))
	    (t (forward-char 1))))
    found))
	      

(defun info-deannotate-region (beg end)
  (interactive "r")
  (format-deannotate-region beg end info-translations
			    'info-next-annotation))



    Oliver
-- 
Oliver Scholz               8 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: terminal escapes in Info files?

[Oliver Scholz]

karl@freefriends.org (Karl Berry) writes:

[...]
> I don't see any particular advantage to writing ^H^[bold^H^] (or <bold>
> or whatever) instead of ^[[3m, and the implementation in both info and
> M-x info gets much more complex if we introduce a layer of indirection,
> which all it really amounts to.
[...]

With all due respect, I don't see an improvement in using ANSI escape
sequences. Maybe old tty info readers would send the escape sequences
to the terminal, but you'd still need an Emacs info reader which is up
to date, anyways. Given that you have compatibility issues in either
case, I'd like to plea for a syntactical markup.

^H^[code^H^] and ^H^[example^H^] or ^H^[emph^H^] for example, if that
fits to the current info file format.

    Oliver
-- 
Oliver Scholz               8 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: terminal escapes in Info files?

[Eli Zaretskii]

> From: Oliver Scholz <epameinondas@gmx.de>
> Date: Wed, 29 Oct 2003 13:52:39 +0100
> 
> With all due respect, I don't see an improvement in using ANSI escape
> sequences.

The improvement, quite obviously, is that the stand-alone Info reader,
which is text-mode based, will be able to display attributes such as
bold, underline, italics, and (on color-capable terminals) colors, and
it will be able to do that without any changes whatsoever in the
reader's own code (at least the part of it that runs on Unix and GNU
systems; DOS and Windows might need some adaptation).

> Maybe old tty info readers would send the escape sequences
> to the terminal, but you'd still need an Emacs info reader which is up
> to date, anyways.

The assumption was that the Emacs Info reader can easily translate the
escapes into faces.  ansi-colors.el already shows how.

> Given that you have compatibility issues in either
> case, I'd like to plea for a syntactical markup.

So you propose to have 2 problems instead of one, yes?

Re: terminal escapes in Info files?

[Eli Zaretskii]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 997 bytes --]

> From: Oliver Scholz <epameinondas@gmx.de>
> Date: Wed, 29 Oct 2003 13:20:25 +0100
> 
> The HTML for C-h i would not need to be “real” HTML, just something
> which would look like HTML to a browser.
> [...]
> <!-- [info file] -->
> <html>
> <h1>Defining Functions</h1>
> 
> <p>   We usually give a name to a function when it is first created.  This
> is called "defining a function", and it is done with the `defun'
> special form.</p>
> 
> <p> - Special Form: <b>defun</b> name argument-list body-forms
>      `defun' is the usual way to define new Lisp functions.  It defines
>      the symbol NAME as a function that looks like this:</p>
> 
> <code class="example"><pre>     
>           (lambda ARGUMENT-LIST . BODY-FORMS)
> </pre></code>

IMHO, to get the standalone Info to support such a format, it would
require a major rewrite.  Currently, the display code of the
standalone reader basically just writes the text as-is to the screen;
what you suggest would make its job much harder.

Re: terminal escapes in Info files?

[Andreas Schwab]

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

> The improvement, quite obviously, is that the stand-alone Info reader,
> which is text-mode based, will be able to display attributes such as
> bold, underline, italics, and (on color-capable terminals) colors, and
> it will be able to do that without any changes whatsoever in the
> reader's own code (at least the part of it that runs on Unix and GNU
> systems; DOS and Windows might need some adaptation).

Depends on your definition of "without any changes whatsoever".  The one
from texinfo 4.6 can't.

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux AG, Deutschherrnstr. 15-19, D-90429 Nürnberg
Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: terminal escapes in Info files?

[Oliver Scholz]

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

>> From: Oliver Scholz <epameinondas@gmx.de>
[...]
>> Maybe old tty info readers would send the escape sequences
>> to the terminal, but you'd still need an Emacs info reader which is up
>> to date, anyways.
>
> The assumption was that the Emacs Info reader can easily translate the
> escapes into faces.  ansi-colors.el already shows how.

And yet you'd need to hack the Emacs info reader in order to make
sure that it uses ansi-color.el. Maybe the patch is trivial, even
easier than stripping markup using format.el. But it won't work out
of the box for all users.

>> Given that you have compatibility issues in either
>> case, I'd like to plea for a syntactical markup.
>
> So you propose to have 2 problems instead of one, yes?

Yes, indeed, because IMO using ANSI escape sequences is a step into
the wrong direction, while introducing (a few) syntactical markup tags
is a step into the right direction. YMMV, but my personal opinion: Iff
you want to change the info format at all, please do it by introducing
syntactical markup.

    Oliver
-- 
Oliver Scholz               8 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: terminal escapes in Info files?

[Oliver Scholz]

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

[...]
> IMHO, to get the standalone Info to support such a format, it would
> require a major rewrite.  Currently, the display code of the
> standalone reader basically just writes the text as-is to the screen;
> what you suggest would make its job much harder.

That's a pity. However, maybe you could consider it as an option for
the info format in the future, whether or not you introduce ANSI
escape sequences for now. Actually I suggested it in a response to
Stefan just as a way to get something like HTML without writing a real
HTML renderer. Personally I wouldn't care as much about the actual
format as long as it is syntactical.

But on a second thought, I think one big benefit of something
HTML-like is that users who don't use Emacs and who don't like the tty
reader could use their favourite browser to read the info files in the
system's central info directory. IIRC desctop environments like KDE or
Gnome already use a browser for their “help desk”, for example (or has
that changed since the last time I looked?).

    Oliver
-- 
Oliver Scholz               8 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: terminal escapes in Info files?

[Robert J. Chassell]

Oliver Scholz <epameinondas@gmx.de> wrote

    IIRC desctop environments like KDE or Gnome already use a browser
    for their “help desk” ...

Yes, they do; and that means that their online help is worse than the
online help I read in the mid-1980s.  They have retrogressed a
generation.

Web browsers waste effort; you cannot navigate through HTML documents
quickly and easily as you can with Info.  HTML is one of the poorer
designs.

In addition to printed output and Info, Texinfo produces HTML output
as a surface expression.  This means that there is no need to make
Info as inefficent as HTML.  At the very least, please keep Info up to
the efficiency of the 1980s.

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

Re: terminal escapes in Info files?

[Eli Zaretskii]

> From: Oliver Scholz <epameinondas@gmx.de>
> Date: Wed, 29 Oct 2003 17:24:03 +0100
> 
> But on a second thought, I think one big benefit of something
> HTML-like is that users who don't use Emacs and who don't like the tty
> reader could use their favourite browser to read the info files

I see your point, but please note that there are more Info readers
than just the standalone Info and Emacs are.  The other readers are
less known, I think, but they still exist and support GUI-like
features.  TkInfo is one of them, for instance.

So if someone doesn't like the standalone reader and doesn't use
Emacs, they still have some alternatives before turning to a Web
browser.

Re: terminal escapes in Info files?

[Alper Ersoy]

Andreas Schwab:
> Depends on your definition of "without any changes whatsoever".  The one
> from texinfo 4.6 can't.

You are wrong.  Please see the -R option.

Karl made it the default behaviour a few days ago.

Thanks,

-- 
Alper Ersoy

Re: terminal escapes in Info files?

[Reiner Steib]

On Wed, Oct 29 2003, Oliver Scholz wrote:

> But on a second thought, I think one big benefit of something
> HTML-like is that users who don't use Emacs and who don't like the tty
> reader could use their favourite browser to read the info files 

Producing HTML output from texinfo sources is possible since ages
(texi2html, makeinfo --html, ...).

> in the system's central info directory. IIRC desctop environments
> like KDE or Gnome already use a browser for their “help desk”, for
> example (or has that changed since the last time I looked?).

KDE's "Konquerer" (version 3.1.1) can display info files directly.
Just enter "info:/dir" in the location bar.  The Gnome help browser
("yelp"?), too.

Bye, Reiner.
-- 
       ,,,
      (o o)
---ooO-(_)-Ooo--- PGP key available via WWW   http://rsteib.home.pages.de/

Re: terminal escapes in Info files?

[Stefan Monnier]

> Web browsers waste effort; you cannot navigate through HTML documents
> quickly and easily as you can with Info.  HTML is one of the poorer
> designs.

There is no question that existing web browsers suck and that the Info
viewer is better.  Similarly, there is no question that TeXinfo is
much superior to HTML to write documentation.

But I don't see why the Info format is superior to the HTML markup
language, other than indirectly in terms of the programs currently
available that make use of them.  Could you expand a little?


        Stefan

Re: terminal escapes in Info files?

[Eli Zaretskii]

> From: Andreas Schwab <schwab@suse.de>
> Date: Wed, 29 Oct 2003 15:31:47 +0100
> 
> Depends on your definition of "without any changes whatsoever".  The one
> from texinfo 4.6 can't.

Try "info -R".

Re: terminal escapes in Info files?

[Oliver Scholz]

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

> Oliver Scholz <epameinondas@gmx.de> wrote
>
>     IIRC desctop environments like KDE or Gnome already use a browser
>     for their “help desk” ...
>
> Yes, they do; and that means that their online help is worse than the
> online help I read in the mid-1980s.  They have retrogressed a
> generation.
[...]

> At the very least, please keep Info up to the efficiency of the
> 1980s.
[...]

I had absolutely no intention to suggest anything to make the info
system worse. I love it by heart and despite it deficencies I find it
superior to any other documentation or help system that I know.

All I said is that a) the info file format should in the long run
support more syntactical information and b) that it is a good idea to
choose a markup in such a way that a browser would render it as
HTML. More precisely put:

I suggested a subset of HTML (XHTML compatible to HTML) with the
additional two conventions:

     1. Some of the markup is taken as providing the information
        necessary for the info reader (like linebreaks, indexes
        etc.). As it was discussed earlier in this thread.

     2. The file contains all the necessary whitespace characters, so
        that simply stripping the markup would result in a properly
        formatted plain text file.

All that a minimal conforming UA would have to parse is the markup
that is used for 1), it could then simply strip all the other markup
and dump it on the screen.

I believe that this is a way to get more syntactical markup with no
more work than what would be required for any other syntactical
markup. (That might still be too much, as Eli pointed out. But I
think, at least in the long run it should happen.)

If that is true, then I say that it is a good idea too choose HTML,
because some people could use their browsers to view the files and
other help systems could directly link to the files of the info
system. This is surely suboptimal, but if somebody really wants to use
her browser, there is no need to raise artificial impediments.

[After all, being an Emacs user of the “I do everything inside of
Emacs” sort, I can imagine that some people would prefer to use the
browser with which they are already familiar. It is a good thing if
you can limit the number of applications you use and thus the number
of different user interfaces. People that do not use Emacs, have not
seen the light yet. But what is there to do other than trying to
spread the gospel?]


    Oliver
-- 
Oliver Scholz               8 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: terminal escapes in Info files?

[Oliver Scholz]

Reiner Steib <4.uce.03.r.s@nurfuerspam.de> writes:

> On Wed, Oct 29 2003, Oliver Scholz wrote:
>
>> But on a second thought, I think one big benefit of something
>> HTML-like is that users who don't use Emacs and who don't like the tty
>> reader could use their favourite browser to read the info files 
>
> Producing HTML output from texinfo sources is possible since ages
> (texi2html, makeinfo --html, ...).

I guess you are aware that this is not what we are talking about.

[...]
> KDE's "Konquerer" (version 3.1.1) can display info files directly.
> Just enter "info:/dir" in the location bar.  The Gnome help browser
> ("yelp"?), too.
[...]

Well, that's something. Thanks for the information.

    Oliver
-- 
Oliver Scholz               8 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: terminal escapes in Info files?

[Alper Ersoy]

Alper Ersoy:
> Karl made it the default behaviour a few days ago.

A bit of self correction here.  As it seems I misread the ChangeLog
bit.  However, I believe it should be the default, before a release.

-- 
Alper Ersoy

Re: terminal escapes in Info files?

[Richard Stallman]

      1) Older versions friendly,
      2) Future versions friendly.

    (1) is using ANSI escapes directly in Info files.  The benefit is,
    these files will still be displayed correctly by older versions of
    info when -R option is given (though I'm not sure about emacs.) 

it wont work in emacs.

    The downside is, Info becomes an intermediate format rather than
    a final one, always asking for an additional step in the browsers.
    Display will be totally screwed in older versions[1].

this is true for both #1 and #2.  both would need conversion
for emacs to display them.  both would need conversion to
display them properly in stand-alone info, on a non-ansi terminal.

Re: terminal escapes in Info files?

[Richard Stallman]

Is HTML adequate for the job of replacing info format?  Yes, it does
something vaguely similar, but that does not mean the answer is yes.
Does the HTML output produced by makeinfo give just as good results in
a browser as info files do in the info readers?  Can we support *all*
the features of info just as well as we do now?

One other obstacle to using HTML instead of info format is that emacs
does not contain a browser at present.  We have considered for years
the idea of installing the W3 package into Emacs, but (from what I
recall) it does not work as well as ordinary browsers.  So I hesitate
to replace info.el with W3.

Re: terminal escapes in Info files?

[Richard Stallman]

    Since Info is inherently limited to what can be displayed on a terminal,
    it seems like ANSI escape sequences are as reasonable specification of
    the capabilities as anything else?

Info files can be displayed under X and we need not assume they are
limited to a narrow range of display features forever.  But even if we
never support anything beyond what terminal escape sequences can do,
we still should not use them.  There is nothing particularly easy
about converting terminal escape sequences into text properties for
emacs to display.

Re: terminal escapes in Info files?

[Richard Stallman]

    rms: I am actually coming to believe that using the raw terminal escape
    sequences is as clean as anything else in this particular limited
    context.

I firmly disagree.  Perhaps it is a good idea to use ESC to start
these sequences, so that nothing in existing info files needs to be
changed, but we should certainly use something easier to understand
than those irrelevant ASCII escape sequences to specify the meaning of
the markup.  We do want to specify things as a higher level, not the
terminal colors.  And we should use a clean syntax, perhaps HTML
markup constructs.

Re: terminal escapes in Info files?

[Oliver Scholz]

Oliver Scholz <epameinondas@gmx.de> writes:

[...]
>      1. Some of the markup is taken as providing the information
>         necessary for the info reader (like linebreaks, indexes
                                              ^^^^
>         etc.). As it was discussed earlier in this thread.
[...]

That was meant to be „page breaks“.

    Oliver
-- 
Oliver Scholz               8 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: terminal escapes in Info files?

[Eli Zaretskii]

> Date: Wed, 29 Oct 2003 21:45:44 +0200
> From: Alper Ersoy <dirt@gtk.org>
> 
> Speaking for stand-alone info, there already is stripping
> functionality that kicks in when viewing man pages without the -R
> option.  Likewise if emacs' browser is capable of viewing man pages,
> it too should have such functionality already.

It does (by means of an awk script it runs as a subprocess when it
prepares the man page for display).

Re: terminal escapes in Info files?

[Alper Ersoy]

Richard Stallman:
>     The downside is, Info becomes an intermediate format rather than
>     a final one, always asking for an additional step in the browsers.
>     Display will be totally screwed in older versions[1].

> this is true for both #1 and #2.  both would need conversion
> for emacs to display them.  both would need conversion to
> display them properly in stand-alone info, on a non-ansi terminal.

Speaking for stand-alone info, there already is stripping
functionality that kicks in when viewing man pages without the -R
option.  Likewise if emacs' browser is capable of viewing man pages,
it too should have such functionality already.

-- 
Alper Ersoy

Re: terminal escapes in Info files?

[David Kastrup]

Richard Stallman <rms@gnu.org> writes:

> Is HTML adequate for the job of replacing info format?  Yes, it does
> something vaguely similar, but that does not mean the answer is yes.
> Does the HTML output produced by makeinfo give just as good results
> in a browser as info files do in the info readers?  Can we support
> *all* the features of info just as well as we do now?

I don't think that the main idea was to replace the various info
readers by browsers, but to change the info format to a strict subset
of HTML, and then make the info readers recognize this subset as an
external format.

The info readers would not need to be able to understand arbitrary
HTML, just the specific HTML subset output by whatever tool was used
for generating it, and native HTML browsers would not necessarily
support everything the info readers could.

I think the first sensible step would be to augment the HTML
generating scripts in the texinfo distribution so as to include the
_complete_ information available in info file format, probably as
some tags usually ignored by typical HTML browsers.

Once the complete information is available in the HTML files, one can
write a reader for it.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: terminal escapes in Info files?

[Luc Teirlinck]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 496 bytes --]

Oliver Scholz wrote:

   Oliver Scholz <epameinondas@gmx.de> writes:

   [...]
   >      1. Some of the markup is taken as providing the information
   >         necessary for the info reader (like linebreaks, indexes
						 ^^^^
   >         etc.). As it was discussed earlier in this thread.
   [...]

   That was meant to be „page breaks“.

I guess you must still mean something else (Info has no pages and
thus, no page breaks.  Page breaks are for the printed output.)

Sincerely,

Luc.

Re: terminal escapes in Info files?

[Oliver Scholz]

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

> Oliver Scholz wrote:
[...]
>    That was meant to be „page breaks“.
>
> I guess you must still mean something else (Info has no pages and
> thus, no page breaks.  Page breaks are for the printed output.)

Well, not being a native speaker I am not aware of all of the
connotations of the English word “page”. So I may have chosen it
wrongly. (Don't you say “HTML page” in English, too?)

I mean the current info format's \x1f

Which is the the English word you use for the structural equivalent
of a printed's output page, i.e. the electronic text that is rendered
on an application's screen canvas at a certain time?

    Oliver
-- 
Oliver Scholz               8 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: terminal escapes in Info files?

[Andreas Schwab]

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

>> From: Andreas Schwab <schwab@suse.de>
>> Date: Wed, 29 Oct 2003 15:31:47 +0100
>> 
>> Depends on your definition of "without any changes whatsoever".  The one
>> from texinfo 4.6 can't.
>
> Try "info -R".

Ok, I didn't know about that.

Btw., the help text is misleading, info without -R does not actually
remove the escapes, it displays them as replacement characters instead.

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux AG, Deutschherrnstr. 15-19, D-90429 Nürnberg
Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: terminal escapes in Info files?

[Alper Ersoy]

Andreas Schwab:
> Btw., the help text is misleading, info without -R does not actually
> remove the escapes, it displays them as replacement characters instead.

Aha!  A chance for me to fix my mistake :)  Karl's change that
I mentioned actually fixes the message.  This is the new one:

  -R, --raw-escapes            don't remove ANSI escapes.

Thanks,

-- 
Alper Ersoy

Re: terminal escapes in Info files?

[Eli Zaretskii]

> From: Andreas Schwab <schwab@suse.de>
> Date: Wed, 29 Oct 2003 22:08:11 +0100
> 
> Btw., the help text is misleading, info without -R does not actually
> remove the escapes, it displays them as replacement characters instead.

Well, yes and no: it does remove some control characters such as \b
and \f.  The same code is used to convert ^c into two ASCII
characters, so it's kinda hard to write a short but accurate help
message.

Re: terminal escapes in Info files?

[Eli Zaretskii]

> From: David Kastrup <dak@gnu.org>
> Date: 29 Oct 2003 20:47:46 +0100
> 
> I think the first sensible step would be to augment the HTML
> generating scripts in the texinfo distribution so as to include the
> _complete_ information available in info file format, probably as
> some tags usually ignored by typical HTML browsers.

HTML browsers don't ignore anything, they just don't have commands to
look up menus generated for indices, and don't have search commands
that look up entire documents, not only single pages.

I may be forgetting something, but in general I don't think there's
some Texinfo markup we don't put into HTML as we do into Info format.

Re: terminal escapes in Info files?

[David Kastrup]

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

> > From: David Kastrup <dak@gnu.org>
> > Date: 29 Oct 2003 20:47:46 +0100
> > 
> > I think the first sensible step would be to augment the HTML
> > generating scripts in the texinfo distribution so as to include the
> > _complete_ information available in info file format, probably as
> > some tags usually ignored by typical HTML browsers.
> 
> HTML browsers don't ignore anything,

Not even comments?

> I may be forgetting something, but in general I don't think there's
> some Texinfo markup we don't put into HTML as we do into Info
> format.

So then it should be conceivable to use this HTML as a different info
file format.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: terminal escapes in Info files?

[Luc Teirlinck]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 936 bytes --]

Oliver Scholz wrote:

   Well, not being a native speaker I am not aware of all of the
   connotations of the English word “page”. So I may have chosen it
   wrongly. (Don't you say “HTML page” in English, too?)

   I mean the current info format's \x1f

   Which is the the English word you use for the structural equivalent
   of a printed's output page, i.e. the electronic text that is rendered
   on an application's screen canvas at a certain time?

Sorry, I misunderstood "page break" as referring to the info command
@page, which would clearly have made no sense in Info.  I believe the
info format's ^_ (in .info files) is normally referred to as a node
boundary, since in this context ^L is a page boundary.  I usually just
write ^_, ^L or @page to leave no ambiguity.  But essentially, I guess
I just misunderstood you by jumping in a discussion I had not
completely been following from the beginning.

Sincerely,

Luc.

Re: terminal escapes in Info files?

[Robert J. Chassell]

   But I don't see why the Info format is superior to the HTML markup
   language, ...

By default, HTML does not distinguish between references to another
part of the same document on a different HTML page and references to a
different document.  This means that you cannot search through a
multi-page document.  The `find next part' component of a regexp
search engine cannot be sure it is finding the next part close by.
You cannot navigate efficiently using search.

Of course, good writers can write good documents, and only make proper
references; but this depends on a writer going against the design of
the language.  The capability is there, but writers can, and most do,
ignore the capability.  Indeed, major Web browsers lack default key
bindings for `next', `previous', and `up' pages of a document --
probably for the good reason that the keys would fail on most Web
sites.

I have the strong impression that those who browse the Web do not know
that it is possible and pleasant to navigate efficiently through a
multi-page document by pressing the space bar or with regular
expression searches.  They are impressed by the advantages of the Web
over printed-book libraries and filing cabinets and do not realize
they are missing computer features that have been available for a
generation.

Also writers have a tendency to use various HTML features, like side
bars, that work find for sighted readers with fast connections, but
which cause trouble when the reader is using a slow connection.

Moreover, as a practical matter, writers of HTML documents tend to
think of their readers as sighted rather than blind.  They tend to
depend on pictures.  They do not think of a sighted expert with a slow
connection as effectively blind; they do not think of the permanently
blind.

This over-dependence on images is not an HTML design feature.  The
problems imposed cannot be blamed on HTML, like the problem with
efficient navigation.  But the problem does tend to accompany Web
browsers and HTML documents.

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

Re: terminal escapes in Info files?

[Robert J. Chassell]

   ... (Don't you say “HTML page” in English, too?)

Yes, but English speaks do not mean the same when when referring to a
printed page and an HTML page.  The use of the term in HTML is a
metaphorical extension of the concept of `printed page'.


   I mean the current info format's \x1f

I think you meant `node', which if it were printed may print out as
more or less than one printed page.  A node is also sometimes called a
`section'.  But in Texinfo documents, sections often consist of
several nodes, and then of course, there is the `@section' command.
The language is confusing.

   Which is the the English word you use for the structural equivalent
   of a printed's output page, i.e. the electronic text that is rendered
   on an application's screen canvas at a certain time?

The `display' or `buffer' or `window'.  The amount displayed varies
depending on how many lines your window is showing.  For example,
right now my display is showing 48 lines for this *mail* buffer, but
just a few moments ago, I divided this frame into two and my display
was showing only 24 lines for this buffer.

In HTML, the word that corresponds to a `node' or `section' is a
`page'.  It is what you get when you fetch a URL.

Put another way, a URL points to a page.

Thus, `http://www.teak.cc' points the the default page indicated by
the URL, which is the `index.html' page.

An HTML page may print out as more or less than one printed page.
Often, an HTML page is larger than the amount that is displayed by a
Web browser at any one time.

I have read people using the word `document' to mean one page of an
HTML document.  By this usage, the W3 mode manual splits into 129
different documents when created as HTML using the default.  I find
this language confusing, since in fact, the W3 mode manual is a single
manual, one `document'.

The `(texinfo)HTML Splitting' node in Info says, 

    By default, `makeinfo' splits HTML output into one output file per
    Texinfo source node.

which is much clearer.  (The `--no-split' option produces one HTML
page from one Texinfo source file.)

All in all the language is confusing, and not everyone uses it the
same way.

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

Re: terminal escapes in Info files?

[Robert J. Chassell]

       I mean the current info format's \x1f

    I think you meant `node'...

My apologies.  I misled you.  The \x1f marks the beginning of a node,
not a node itself.  It is a node boundary.  The node is the text
between two such marks or between such a mark and the beginning or end
of a file.  (Or maybe a node includes such a mark....)

Twenty years or more ago, people wrote Info files directly.  This was
before Texinfo.  At that time, it was important to know how to mark
the beginning of a node.  Texinfo was invented in the 1980s, and since
then people have avoided writing directly in Info.  This is because we
want outputs -- `surface expressions' -- in multiple formats: not only
Info, but HTML, XML, PS, PDF, DVI, and so on.

Nowadays, only makeinfo maintainers like Karl are likely to know
about, and a few eccentric experts.

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

Re: terminal escapes in Info files?

[Richard Stallman]

    The HTML for C-h i would not need to be ?real? HTML, just something
    which would look like HTML to a browser. What I mean is: It could be
    like the text/enriched format (whitespace being significant, so that
    you get a nice plain text when you just strip the markup), but with
    tags borrowed from HTML:

If we combine this idea with the idea of using an ESC character before
each <...> sequence, perhaps the result could be such that we can make
the info reader handle old info files correctly also.

Re: terminal escapes in Info files?

[Eli Zaretskii]

> From: David Kastrup <dak@gnu.org>
> Date: 29 Oct 2003 23:39:00 +0100
> 
> "Eli Zaretskii" <eliz@elta.co.il> writes:
> 
> > > From: David Kastrup <dak@gnu.org>
> > > Date: 29 Oct 2003 20:47:46 +0100
> > > 
> > > I think the first sensible step would be to augment the HTML
> > > generating scripts in the texinfo distribution so as to include the
> > > _complete_ information available in info file format, probably as
> > > some tags usually ignored by typical HTML browsers.
> > 
> > HTML browsers don't ignore anything,
> 
> Not even comments?

Sorry, it seems I completely misunderstood what you were saying in the
sentence to which I responded.  I thought you were saying that HTML
browsers ignore some parts of the HTML output produced by makeinfo,
and that is why they are less efficient for reading a manual.

Thus, this paragraph:

> > I may be forgetting something, but in general I don't think there's
> > some Texinfo markup we don't put into HTML as we do into Info
> > format.
> 
> So then it should be conceivable to use this HTML as a different info
> file format.

Sure, it's conceivable, it just requires a thorough rewrite of the
standalone reader.

Re: terminal escapes in Info files?

[Stephen J. Turnbull]

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

    Stefan>    But I don't see why the Info format is superior to the
    Stefan> HTML markup language, ...

    Robert> By default, HTML does not ...

We're not talking about "default" HTML.  True, people using normal
browsers will continue to "enjoy" the "Windows experience".  Too bad
for them.

But there is no reason why HTML produced by a documentation system
shouldn't _require_ (and enforce, by automatically producing them from
eg Texinfo source)

<!-- sibling nodes happen to be in the same file -->
<link rel="prev" "#prev_node"    -- standard in HTML 4.01 (sec 6.12) -- >
<link rel="next" "#next_node"    -- standard in HTML 4.01 (sec 6.12) -- >
<link rel="up"   "up_node.html"  -- a nonstandard link -- >
<link rel="top"  "document.html" -- a nonstandard link -- >
<link rel="dir"  "../index.html" -- a nonstandard link -- >

The only real disadvantage vis-a-vis traditional Texinfo is the
verbosity.  I think the technical problems are reasonably
straightforward; we can have decent Info-style presentation of
automatically-produced HTML within Info or Emacs.

My guess is that HTML provides all the features needed to provide a
target language isomorphic to Info, and it would be at most a couple
days' work to port Emacs's Info reader to such a language.  The
standalone Info reader might or might not be much harder.  I have no
idea how hard it would be to get makeinfo to produce it.

(Not volunteering; I'm perfectly happy with existing Info.  But it
looks to be easy enough that anybody who advocates HTML should be
required to produce such an isomorphic spec and software that provides
all the features that Info currently does.)

Hm ... I suppose texinfo XML provides all this already?

-- 
Institute of Policy and Planning Sciences     http://turnbull.sk.tsukuba.ac.jp
University of Tsukuba                    Tennodai 1-1-1 Tsukuba 305-8573 JAPAN
               Ask not how you can "do" free software business;
              ask what your business can "do for" free software.

Re: terminal escapes in Info files?

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Date: Wed, 29 Oct 2003 23:19:31 -0500
> 
> If we combine this idea with the idea of using an ESC character before
> each <...> sequence, perhaps the result could be such that we can make
> the info reader handle old info files correctly also.

I doubt that.  Currently, unless invoked with the -R switch, the
standalone reader converts ESC into the ASCII string "^[", but doesn't
remove anything else.  So you will see "^[<...>" for each such
sequence.

Or am I missing something?

Re: terminal escapes in Info files?

[Alper Ersoy]

Hi!

Oliver Scholz:
> Most notably the markup could be syntactical rather than specifying
> the colours to use. I *hate* it, if a document tells me the best
> colour for me to read a certain syntactic element. Let the document
> specify the syntactical element and let me customize the colour.

Ok.  If we lean towards a syntactical markup, it should _also_ specify
the best colour, typeface, etc. too.  We must do this, otherwise
whenever there's a new command in Texinfo, readers will be unaware of
how to handle it.  Something like (notation aside):

  ^H^[var bi^H^]Variable^H^[/var^H^]

So it's bold-italic.  But you (info reader) know it's a var, so you
can use whatever style you want.  Sometime in the future, when we have
this @funky command:

  ^H^[funky sb,red^H^]Art Vandelay^H^[/funky^H^]

You don't know what a funky text is, but you can use the style
provided there.

However, I suggested ANSI escapes in the first place because of the
star characters around strong text.  One can use @strong only, and
still get a flowing text in display environments supporting bold
typeface.  Not with Info though.

Introducing syntactical markup elements is IMHO burning your blanket
because of one flea.

The only way to justify changes this level is to also identify the
other problems in Info, and to address them all at once, then declare
it as Info2.  After all, we are breaking compatibility here, so it
_must_ have to offer more.

Currently though, Info serves as the 'final destionation of
documents.'  So what's wrong with using a widely adopted and frozen
standard? (ECMA-48)

> Another old wish of mine is that the info format could specify the
> type of code, for example (I am using an XML-like notation here,
> because I am not familiar with the info file format):

This has to be addressed in Texinfo first.  Admittedly, I could never
understand @lisp.  Why not

  @example lisp
  ...
  @end example

  @example C++
  ...
  @end example

Like @itemize, @example can accept an optional parameter.  @lisp can
be an alias to ``@example lisp'' internally.  What do you think?

Info doesn't have to format each of these differently, so makeinfo can
omit the rest of @example lines.  However, HTML and XML backends can
clearly make use of this information.

-- 
Alper Ersoy

Re: terminal escapes in Info files?

[Stefan Monnier]

> Also writers have a tendency to use various HTML features, like side

Robert,

You're speaking to the choir here.  The message to which you're responding
made it very clear that I was not talking about HTML written by humans
but about HTML written by `makeinfo'.


        Stefan

Re: terminal escapes in Info files?

[Richard Stallman]

      Likewise if emacs' browser is capable of viewing man pages,
    it too should have such functionality already.

yes, people say that Emacs Lisp code to display those escape sequences
exists.  that would reduce the amount of work for implementing this
change, but wouldn't alter the fact that Info won't handle these
sequences without a change.

I will say yes to something like this only if it uses a cleaner design.
not with terminal escape sequences.

That is my final decision.

Re: terminal escapes in Info files?

[Richard Stallman]

    I don't think that the main idea was to replace the various info
    readers by browsers, but to change the info format to a strict subset
    of HTML, and then make the info readers recognize this subset as an
    external format.

this might be an ok idea, if people work out the details.
it would be a totally incompatible change, though.

Re: terminal escapes in Info files?

[Robert J. Chassell]

"Stephen J. Turnbull" <stephen@xemacs.org> wrote

   .... But there is no reason why HTML produced by a documentation
   system shouldn't _require_ (and enforce, by automatically producing
   them from eg Texinfo source)

   <!-- sibling nodes happen to be in the same file -->
   <link rel="prev" "#prev_node"    -- standard in HTML 4.01 (sec 6.12) -- >
   <link rel="next" "#next_node"    -- standard in HTML 4.01 (sec 6.12) -- >
   <link rel="up"   "up_node.html"  -- a nonstandard link -- >
   <link rel="top"  "document.html" -- a nonstandard link -- >
   <link rel="dir"  "../index.html" -- a nonstandard link -- >

Yes, I agree that makeinfo with the `--html' option should produce
this (and the equivalents for the more usable case in which 
sibling nodes are in different files).

Then, we need to provide a Web browser in Emacs that can make use of
these nodes.  I would especially like to see a function called
`HTML-search' that provides the same capabilities as `Info-search'.

Also, as a practical matter, it would be good to tell people the
appropriate key bindings needed for Mozilla and its deriviatives,
Galeon and Firebird, for Konqueror, and for Lynx.  (It would be nice
to encourage the developers of these programs to provide a regexp
`HTML-search' capability for multi-page documents that are properly
written.)

   My guess is that HTML provides all the features needed to provide a
   target language isomorphic to Info, and it would be at most a couple
   days' work to port Emacs's Info reader to such a language.  

I still fail to understand why anyone would want to make the Info
markup language look like a subset of HTML or of an XML when Texinfo
already produces HTML and XML.  Does it not make more sense to upgrade
makinfo's HTML and XML output, and then upgrade Emacs Web browsers to
use that output?  (W3 mode needs upgrading anyhow; if implemented,
this proposal simply increases the need to upgrade W3 mode.
Hmmm.... while thinking about Web browsers, should W3M mode be changed
so that its display looks to someone able to use sight like the
display produced by Mozilla or Konqueror?)

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

Re: terminal escapes in Info files?

[Richard Stallman]

    > If we combine this idea with the idea of using an ESC character before
    > each <...> sequence, perhaps the result could be such that we can make
    > the info reader handle old info files correctly also.

    I doubt that.  Currently, unless invoked with the -R switch, the
    standalone reader converts ESC into the ASCII string "^[", but doesn't
    remove anything else.  So you will see "^[<...>" for each such
    sequence.

We are not talking about the same question.  What I said is that we
*could* make the info reader which handles the new version of the
format continue to handle old info files correctly.

Your example seems to concern new info files and old info readers.  It
is impossible for the new info format, whatever it is, to work in old
info readers with no change to them.

Re: terminal escapes in Info files?

[Thien-Thi Nguyen]

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

   So you propose to have 2 problems instead of one, yes?

if the two problems can be fixed by cooperation between users and
programmers, it is still a better situation than the one problem that
can only be fixed by programmers.

thi

Re: terminal escapes in Info files?

[Stephen J. Turnbull]

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

    Robert> I still fail to understand why anyone would want to make
    Robert> the Info markup language look like a subset of HTML

I don't.  Personally, I would prefer that documentation authors
learned to use their natural languages to express these things
clearly, with the aid of conventions such as RFC 2119.

But it seems we want more kinds of semantically significant markup
(and such markup is probably a more effective means to clearer
documentation than hoping that documentation authors will apprentice
themselves to poets and novelists, or that poets will start writing
programs to document).

I don't see a good argument for extending the traditional Info markup
that way, especially not by creating yet another non-standard markup
language.  There should be no need for texi2html or makeinfo --html;
the fact that we've been forced to accept such abominations means we
screwed up somewhere.  Consider how successful the man reader is in
standalone Info; I only realized what was happening a few weeks ago
;-), but already I'm mostly trained to type "info" instead of "man".
But I can't do that with (say) the Common Lisp Hyperspec.  That's
Horribly Wrong[tm].

We should work to make good navigation a part of all documentation,
rather than adding "catch-up" presentation features to the ever-
smaller fraction of the body of documentation accessible to Info
browsers.  People should be writing to the authors of "standard" HTML
documentation asking them to provide the HTMLInfo browser navigation
features that "official GNU" documentation does.  Having "ESC<bold>"
sequences in Info documentation is not going to do that.

-- 
Institute of Policy and Planning Sciences     http://turnbull.sk.tsukuba.ac.jp
University of Tsukuba                    Tennodai 1-1-1 Tsukuba 305-8573 JAPAN
               Ask not how you can "do" free software business;
              ask what your business can "do for" free software.