State of the art in Emacs outlining?

State of the art in Emacs outlining?

[Tom Davey]

Is there a preferred elisp package (or combination) in use today for
Emacs outlining? I am a little confused by the several packages out
there -- outline.el, of course, and allout.el and folding.el and others
less known that promise improvements to outline.el -- and I thought I'd
ask about them before jumping in to learn one. 

I'm mainly interesting in ordinary document production rather than
outlining for source code files, but all thoughts are gratefully
welcomed. 

Kai, I read through the thread on emacs-devel called "ill-advised
changes [was key bindings in hideshow.el]" (Feb. 2001), which discusses
outline major-mode and the desirability of an "always-on" structual
overview utility and which includes posts between yourself and RMS, but
this newbie is still a bit confused. :-)

Thanks,
Tom Davey

-- 
Tom Davey
tom@tomdavey.com
blog: http://www.monstersfromtheid.com/

Re: State of the art in Emacs outlining?

[Alex Schroeder]

"Tom Davey" <tdavey@sputnik.com> writes:

> Is there a preferred elisp package (or combination) in use today for
> Emacs outlining? I am a little confused by the several packages out
> there -- outline.el, of course, and allout.el and folding.el and others
> less known that promise improvements to outline.el -- and I thought I'd
> ask about them before jumping in to learn one. 

I think your best bet is to stick to the Emacs standard until you have
specific needs.  These standard modes will be supported, improved, and
eventually replaced by other versions of backwards-compatible stuff --
so you're always on the safe side.  A no-brainer.

Some people have collected descriptions and opinions here:

http://www.emacswiki.org/cgi-bin/wiki.pl?CategoryOutline

Alex.

Re: State of the art in Emacs outlining?

[Kai Großjohann]

"Tom Davey" <tdavey@sputnik.com> writes:

> Is there a preferred elisp package (or combination) in use today for
> Emacs outlining? I am a little confused by the several packages out
> there -- outline.el, of course, and allout.el and folding.el and others
> less known that promise improvements to outline.el -- and I thought I'd
> ask about them before jumping in to learn one. 
>
> I'm mainly interesting in ordinary document production rather than
> outlining for source code files, but all thoughts are gratefully
> welcomed. 

The NEWS file is in outline mode.  I've used outline mode myself,
it's easy to use and provides its functionality well.  For document
production, that seems to be the way to go.

> Kai, I read through the thread on emacs-devel called "ill-advised
> changes [was key bindings in hideshow.el]" (Feb. 2001), which discusses
> outline major-mode and the desirability of an "always-on" structual
> overview utility and which includes posts between yourself and RMS, but
> this newbie is still a bit confused. :-)

I've browsed part of that thread, but it seems that the thread is
about keybindings only.  I think that won't have much effect on
outline (major) mode, since they are talking about minor modes only.

kai
-- 
~/.signature is: umop ap!sdn    (Frank Nobis)

RE: State of the art in Emacs outlining?

[Tom Davey]

Alex, 

Thanks to you and Kai for your replies. The advice is sound -- learn
standard outlining first, and then worry about enhanced packages once I
figure out what else I need. My worry is that I already know what I
need: easier repositioning of items and trees (demoting/promoting),
which allout.el and others packages seem to promise. But really I'm just
guessing, so I'll be patient. 

Thanks also for the link to the Emacs Wiki. The site is a tremendous
resource. I go there often!

Tom Davey

-- 
Tom Davey
tom@tomdavey.com
blog: http://www.monstersfromtheid.com/

Re: State of the art in Emacs outlining?

[Stefan Monnier <foo@acm.com>]

>>>>> "Tom" == Tom Davey <tom@tomdavey.com> writes:
> Thanks to you and Kai for your replies. The advice is sound -- learn
> standard outlining first, and then worry about enhanced packages once I
> figure out what else I need. My worry is that I already know what I
> need: easier repositioning of items and trees (demoting/promoting),
> which allout.el and others packages seem to promise. But really I'm just
> guessing, so I'll be patient. 

The outline.el code in the CVS repository offers such functionality,
although it might be a bit fragile.  I'd be interested to hear how
well it works in practice for others than me.


        Stefan

Re: State of the art in Emacs outlining?

[Sacha Chua]

"Tom Davey" <tdavey@sputnik.com> writes:

> Is there a preferred elisp package (or combination) in use today for
> Emacs outlining? I am a little confused by the several packages out
> there -- outline.el, of course, and allout.el and folding.el and others

I like allout.el because it works well with other modes (although
planner.el and allout.el fight about C-c C-n and other bindings). The
Emacswiki:AllOut page has a note on how to add decent fontlocking. =)

Another thing I like about allout.el is its automatically numbered
lists. It's pretty cool. I also like the fact that allout's pretty
flexible about outline prefixes and the bullets you use. Sometimes the
regexes need a little tweaking, though - I'd been having problems with
allout.el and HTML. Fixed it with a kludge, will get around to filing
a bug report sooner or later. <sheepish grin>

folding.el is probably also really cool, but allout.el's taken care of
all of my needs so far, so I don't really have a compelling reason to
try folding.el out ('cept for the fact that it's there). One of these
days. Maybe you can try out folding.el, allout.el and other outline
major/minor modes you encounter, then write about which one you like
most. <g>

-- 
Sacha Chua <sacha@free.net.ph> - 4 BS CS Ateneo geekette
interests: emacs, gnu/linux, wearables, teaching compsci

Re: State of the art in Emacs outlining?

[Benjamin Rutt]

"Stefan Monnier <foo@acm.com>" <monnier+gnu.emacs.help/news/@flint.cs.yale.edu> writes:

>>>>>> "Tom" == Tom Davey <tom@tomdavey.com> writes:
>> Thanks to you and Kai for your replies. The advice is sound -- learn
>> standard outlining first, and then worry about enhanced packages once I
>> figure out what else I need. My worry is that I already know what I
>> need: easier repositioning of items and trees (demoting/promoting),
>> which allout.el and others packages seem to promise. But really I'm just
>> guessing, so I'll be patient. 
>
> The outline.el code in the CVS repository offers such functionality,
> although it might be a bit fragile.  I'd be interested to hear how
> well it works in practice for others than me.

I've tried it when editing LaTeX.  It seems to work well for promoting
and demoting \section, \subsection and \subsubsection under 'emacs -q'
using the builtin LaTeX mode.

However, it doesn't work quite right with AUCTeX.  Consider the
following test case for AUCTeX:

    \section{foo}

    \subsection{bar}

    \subsubsection{baz}

1) When I position the point anywhere on \subsubsection, M-x
outline-promote turns the line into:

    subsection{baz}

2) When I position the cursor on \section and issue M-x
   outline-demote, the line becomes

    subsection{foo}

In both cases, the opening backslash gets erased.  Hope this helps.
Oh, and I'm not quite using current CVS.  My outline.el is dated May
20, 2002 (don't know if that's current or not).
-- 
Benjamin

Re: State of the art in Emacs outlining?

[Christian Lemburg]

"Stefan Monnier <foo@acm.com>" <monnier+gnu.emacs.help/news/@flint.cs.yale.edu> writes:

> The outline.el code in the CVS repository offers such functionality,
> although it might be a bit fragile.  I'd be interested to hear how
> well it works in practice for others than me.

While I am certainly not using many of the advanced features of
outline-mode, I use it nearly daily for write-ups etc., using txt2html
or txt2tex for making pretty output.

I also have noticed that it is very easy to customize outlook-mode
using appropriate regexes for other purposes, like viewing large files
of source code in an organized manner. The main point here is that you
don't have to understand much to get large gains in productivity
(unlike customizing speedbar, the internals of which I don't grok at
all).

Examples:

(defun perl-outline-mode ()
  "Set customized outline minor mode for Perl"
  (interactive)
  (setq outline-regexp "#!.\\|\\(pac\\)kage\\|sub\\|\\(=he\\)ad\\|\\(=po\\)d")
  (outline-minor-mode))

(defun text-outline-mode ()
  "Set customized outline major mode for text with numbered headings"
  (interactive)
  (setq outline-regexp "[0-9.]+")
  (outline-mode))

(defun php-outline-mode ()
  "Set customized outline minor mode for PHP"
  (interactive)
  (setq outline-regexp "<\\?\\| *function\\|class")
  (outline-minor-mode))


txt2html.pl  \
--heading '^\*\s+\S+' \
--heading '^\*\*\s+\S+' \
--heading '^\*\*\*\s+\S+' \
--heading '^\*\*\*\*\s+\S+' \
--heading '^\*\*\*\*\*\s+\S+' \
--heading '^\*\*\*\*\*\*\s+\S+' \
--heading '^\*\*\*\*\*\*\*\s+\S+' \
--heading '^\*\*\*\*\*\*\*\*\s+\S+' \
--heading '^\*\*\*\*\*\*\*\*\*\s+\S+' \
--heading '^\*\*\*\*\*\*\*\*\*\*\s+\S+' \
--list_prefix_char '[-=o\267]' \
--trim_headings '\*+\s+' \
--number_headings \
--explicit_headings \
"$@"


txt2tex.pl  \
--heading '^\*\s+\S+' \
--heading '^\*\*\s+\S+' \
--heading '^\*\*\*\s+\S+' \
--heading '^\*\*\*\*\s+\S+' \
--heading '^\*\*\*\*\*\s+\S+' \
--heading '^\*\*\*\*\*\*\s+\S+' \
--heading '^\*\*\*\*\*\*\*\s+\S+' \
--heading '^\*\*\*\*\*\*\*\*\s+\S+' \
--heading '^\*\*\*\*\*\*\*\*\*\s+\S+' \
--heading '^\*\*\*\*\*\*\*\*\*\*\s+\S+' \
+EH \
-headingtags number \
--trimheadings '\*+\s+' \
"$@"


DISCLAIMER: Please note that using this with txt2html needs a patched
version of txt2html-1.28 (available from
http://www.aigeek.com/txt2html/ ), see patch below:


diff -Naur txt2html-1.28/txt2html.pl txt2html-1.28-patched/txt2html.pl
--- txt2html-1.28/txt2html.pl	Tue May 23 16:10:26 2000
+++ txt2html-1.28-patched/txt2html.pl	Mon Feb 25 14:49:48 2002
@@ -202,6 +202,14 @@
                                 # in the order they are specified on
                                 # the command line.
 
+# [-nh        ] | [--number_headings               ]
+$number_headings = 0;           # prepend section number to headings
+
+# [-th        ] | [--trim_headings                 ]
+$trim_headings = "";            # regex to trim headings with
+
+# [-lpc       ] | [--list_prefix_char              ]
+$list_prefix_char = "[-=o\\*\\267]"; # character class for list prefixes
 
 # Not implemented yet.
 # [-T <t>:<r> ] | [--tag <tagname>:<regexp>        ]
@@ -347,6 +355,9 @@
      [+l         ] | [--nolink                        ]
      [-H <regexp>] | [--heading <regexp>              ]
      [-EH/+EH    ] | [--explicit_headings / --noexplicit_headings ]
+     [-nh        ] | [--number_headings               ]
+     [-th        ] | [--trim_headings <regexp>        ]
+     [-lpc       ] | [--list_prefix_char <regexp>     ]
      [-ab <file> ] | [--append_body <file>            ]
      [+ab        ] | [--noappend_body                 ]
      [-ah <file> ] | [--append_head <file>            ]
@@ -720,6 +731,26 @@
             next;
         }
 
+        if ($ARGV[0] eq "-nh" || $ARGV[0] eq "--number_headings")
+        {
+            $number_headings = 1;
+            next;
+        }
+
+        if ($ARGV[0] eq "-lpc" || $ARGV[0] eq "--list_prefix_char")
+        {
+            $list_prefix_char = $ARGV[1];
+            shift @ARGV;
+            next;
+        }
+
+        if ($ARGV[0] eq "-th" || $ARGV[0] eq "--trim_headings")
+        {
+            $trim_headings = $ARGV[1];
+            shift @ARGV;
+            next;
+        }
+
         if ($ARGV[0] eq "--")
         {
             last;
@@ -869,7 +900,7 @@
     local($line) = @_;
     local($prefix, $number, $rawprefix);
 
-    return (0,0,0) if (!($line =~ /^\s*[-=o\*\267]+\s+\S/ ) &&
+    return (0,0,0) if (!($line =~ /^\s*$list_prefix_char+\s+\S/ ) &&
                        !($line =~ /^\s*(\d+|[^\W\d_])[\.\)\]:]\s+\S/ ));
 
     ($number) = $line =~ /^\s*(\d+|[^\W\d_])/;
@@ -889,7 +920,7 @@
         $prefix = $rawprefix;
         $prefix =~ s/(\d+|[^\W\d_])//;  # Take the number out
     } else {
-        ($rawprefix) = $line =~ /^(\s*[-=o\*\267]+.)/;
+        ($rawprefix) = $line =~ /^(\s*$list_prefix_char+.)/;
         $prefix = $rawprefix;
     }
     ($prefix, $number, $rawprefix);
@@ -1111,6 +1142,22 @@
     $line =~ s/(<H.>)(.*)(<\/H.>)/$1<A NAME="$anchor">$2<\/A>$3/;
 }
 
+sub trim_heading_maybe
+{
+    if ($trim_headings) {
+	$line =~ s/$trim_headings//g;
+    }
+}
+
+sub number_heading_maybe
+{
+    local($heading_number) = ($line =~ /<A NAME="section-([^"]*)">/);
+    #" keep cperl happy
+    if ($number_headings) {
+        $line =~ s/(<H.><A [^>]*>)(.*)(<\/A><\/H.>)/$1$heading_number $2$3/;
+    }
+}
+
 sub heading_level
 {
     local($style) = @_;
@@ -1150,6 +1197,8 @@
     $heading_level = &heading_level($underline);
     &tagline("H" . $heading_level);
     &anchor_heading( $heading_level );
+    &number_heading_maybe;
+    &trim_heading_maybe;
     $line_action |= $HEADER;
 }
 
@@ -1168,6 +1217,8 @@
             }
             &tagline("H" . $level);
             &anchor_heading( $level );
+	    &number_heading_maybe;
+	    &trim_heading_maybe;
             $line_action |= $HEADER;
             last;
         }


-- 
Christian Lemburg, <lemburg@aixonix.de>, http://www.clemburg.com/


 Disc space -- the final frontier!

Re: State of the art in Emacs outlining?

[Stefan Monnier <foo@acm.com>]

> 1) When I position the point anywhere on \subsubsection, M-x
> outline-promote turns the line into:
>     subsection{baz}

Oops!  Thanks!
I'll fix it,


        Stefan

Re: State of the art in Emacs outlining?

[Matthias Meulien]

Christian Lemburg <lemburg@aixonix.de> wrote:

> (defun text-outline-mode ()
>   "Set customized outline major mode for text with numbered headings"
>   (interactive)
>   (setq outline-regexp "[0-9.]+")
>   (outline-mode))

Anolog with header level support, font-lock-mode. Put the following
lines in `text-mode-hook' for example.

;; Provides outline facilities based on numbered headers.

(defun outline-level ()
  "Return the depth to which a statement is nested in the outline.
Point must be at the beginning of a header line.  This is actually
the number of . characters that `outline-regexp' matches."
  (save-excursion
    (looking-at outline-regexp)
    (let ((string (match-string 0))
	  (level 0))
      (while (string-match "\\." string)
	(setq level (1+ level)
	      string (substring string (match-end 0))))
      level)))

(setq outline-regexp "\\([0-9]+\\.\\)+ ")

(setq imenu-generic-expression
	(list (list nil (concat "^\\(?:" outline-regexp "\\).*$") 0)))

(outline-minor-mode 1)

(set (make-local-variable 'font-lock-defaults)
       '(outline-font-lock-keywords t nil nil backward-paragraph))

(imenu-add-menubar-index)
-- 
Matthias

RE: State of the art in Emacs outlining?

[Tom Davey]

Sacha Chua writes:

> Maybe you can try out folding.el, allout.el and other outline
> major/minor modes you encounter, then write about which one you like
> most. <g>

I shall! I've made a start already, but putting an entry on my blog
about the excellent outlining advice I've received from people via this
very thread:

http://www.monstersfromtheid.com/2002/10/03.html#a120


-- 
Tom Davey
tom@tomdavey.com
blog: http://www.monstersfromtheid.com/