Re: ansi-color documentation (from TODO)

[Alex Schroeder]

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

>> I just read in the Emacs TODO that documentation for ANSI color is
>> needed.  I'm prepared to write it up; I am the ansi-color.el author.
>> I'd start with a texinfo version of what is available on the web and
>> in the commentary.  Missing stuff can be added later.  Would this be
>> for the Emacs manual or the Elisp manual?
> 
> It should be in the user manual, since it's a user-level feature.

Hm, in that case I think the following should be enough.

Should I add a paragraph explaining that ls ought to do the right
thing anyway: Since Emacs sets the TERM variable to dumb, ls should
not produce escape sequences.  If ls does that, the user's setup is
broken: he probably set an alias unconditionally.  This ought to be
fixed.  For most people, however, the workaround using ansi-color will
work.

I could also add one more paragraph explaining what SGR are, how the
garbage looks (example: "^[[01;34mman^[[0m") and what ansi-color does.

All you need to do is say it.  :)

Alex.


cd /home/alex/tmp/
diff -c /home/alex/tmp/misc.texi\~ /home/alex/tmp/misc.texi
*** /home/alex/tmp/misc.texi~   Mon Nov  5 20:22:32 2001
--- /home/alex/tmp/misc.texi    Mon Nov  5 20:45:33 2001
***************
*** 344,349 ****
--- 344,350 ----
  * Term Mode::              Special Emacs commands used in Term mode.
  * Paging in Term::         Paging in the terminal emulator.
  * Remote Host::            Connecting to another computer.
+ * Escape Sequences::       Interpreting escape sequences.
  @end menu
  
  @node Single Shell
***************
*** 986,992 ****
  escape sequences.  Term mode recognizes these escape sequences, and
  handles each one appropriately, changing the buffer so that the
  appearance of the window matches what it would be on a real terminal.
! You can actually run Emacs inside an Emacs Term window.
  
     The file name used to load the subshell is determined the same way
  as for Shell mode.  To make multiple terminal emulators, rename the
--- 987,995 ----
  escape sequences.  Term mode recognizes these escape sequences, and
  handles each one appropriately, changing the buffer so that the
  appearance of the window matches what it would be on a real terminal.
! You can actually run Emacs inside an Emacs Term window.  @xref{Escape
! Sequences}, for a partial implementation of this for ordinary Shell
! mode.
  
     The file name used to load the subshell is determined the same way
  as for Shell mode.  To make multiple terminal emulators, rename the
***************
*** 1140,1145 ****
--- 1143,1177 ----
  off directory tracking.
  
  @end ignore
+ 
+ @node Escape Sequences
+ @subsection Interpreting Escape Sequences
+ @cindex ls --color=yes
+ @cindex garbage ls output in shell mode
+ @cindex Ansi escape sequences
+ 
+ Some programs such as @code{ls} can use escape sequences to produce
+ colorized output.  These escape sequences must be handled by the
+ terminal.  Term mode does this; Shell mode does not.  A filter can be
+ added to shell mode, however, which does the right thing for escape
+ sequences specifying the appearance of text: foreground color,
+ background color, weight, slant, etc.  The filter basically applies
+ Select Graphic Rendition (SGR) control sequences (formerly known as
+ ANSI escape sequences) and tries to translate these into faces.
+ 
+ You can arrange for Emacs to automatically install this filter as
+ follows:
+ 
+ @example
+ (add-hook 'shell-mode-hook 'ansi-color-for-comint-mode-on)
+ @end example
+ 
+ SGR control sequences are defined in section 3.8.117 of the ECMA-48
+ standard (identical to ISO/IEC 6429), which is freely available as a
+ PDF file @url{URL:http://www.ecma.ch/ecma1/STAND/ECMA-048.HTM}.  The
+ "Graphic Rendition Combination Mode (GRCM)" implemented is "cumulative
+ mode" as defined in section 7.2.8.  Cumulative mode means that
+ whenever possible, SGR control sequences are combined.
  
  @node Emacs Server, Hardcopy, Shell, Top
  @section Using Emacs as a Server

Diff finished at Mon Nov  5 20:48:05