Exclude headings from table of contents

Contents

  1. Exclude headings from table of contents
    1. Possible Solutions
    2. Title markup
    3. New markup to hide headings from TOC macro
    4. New macro to produce a pagetitle
    5. TOC macro changed to ignore text before

Since Moin 1.5 we don't have the pagename anymore in the page but in the theme's header. People now start to emulate this old behaviour by introducing h1-headings with some kind of page title or description, then they put the table of contents underneath that (see above). However h1 as new page title is included in the table of contents and this is not wanted.

A related issue is section numbering - when using h1 heading in the page as the page title, the heading is numbered 1. It is possible to configure section numbers to ignore the first level, but it is not a good solution, because it require special effort for the common case.

Possible Solutions

A good solution should work transparently for the common case without any configuration, and should not require converting of existing content in 1.3 or 1.5 wikis.

Title markup

My two cents: Seems like the root of the issue is that some people (myself included) want a way to put a title at the top of the page. If I were writing the spec, the requirements would go something like this:

  1. The title should in no way be interpreted as a heading.

    • Not sure about that. Or to be more precise: It shouldn't be interpreted as heading by the toc macro. But since the page title has some "super"-heading functionality, it should also be marked with the h1 html markup. As far as I can see, this is one criteria for AccessibleMoin (see http://www.w3.org/TR/1999/WAI-WEBCONTENT-19990505/ Checkpoint 3.5: Use header elements to convey document structure and use them according to specification.)

      • So, the only way to make a recognizable (accessible) title is to use H1? If that's the way it is, then sobeit. Unfortunately, since MoinMoin made H1 available after 1.3x, people have started using = H1 = level headings in markup, meaning that will have to change yet again.

  2. The title text must be specifiable in the markup. The themes already show the actual page name, so it does not generally need to be repeated. This requirment would allow the author to form a title different than either the subpage name, or the full page name (path), and that is well suited for the page contents. Example: for a page named Animals/Mammals/EatingHabits/Horse, that is not the greatest title. The subpage name (Horse) is even worse. A much better title might be "What a Horse Eats" or "Horse Diet" depending on the audience.

    • Some of the themes show the title in the header, but it does not really work as a page title. What modern (1.5) does is show bread crumbs in huge font. Of curse Animals/Mammals/EatingHabits/Horse is a horrible page title, however, the sub page name Horse is an excellent title. If you think that the page is about horse diet, why not rename the page to Animals/Mammals/EatingHabits/HorseDiet?

      • I have to disagree... While it could be argued that "Horse" is an OK title, it is in no way an "excellent" title. Changing it to "Horse Diet" is redundant and may not be desirable in the organizational scheme. I could come up with many more examples if you can't imagine them yourself. Also, perhaps not all themes show the full page path, but that does not mean that a title at the top of the content area should have to do it. And that was the whole point of this requirement, let the author coin the title (independently of the official page name).

  3. Further, since we want a title that doesn't act like a header, it would be nice to have one that doesn't look like a header, either. Things like different color, centered, larger than h1, etc., would be nice to have. None of these are possible with headers, since they do not allow markup. (To have a consistent look throughout the wiki, the default look of a title should be configurable for the wiki as a whole.)

    • <h1 class="title"></h1> solve the different look issue, and is configurable by wiki wide CSS.

  4. Eventually, it might be nice to have a way to search only the "friendly" titles, or maybe the pagenames + title.

Why not add some parameters/keywords to TOC ReimarBauer/Photo/img.png -- ReimarBauer 2007-02-10 22:22:41

New markup to hide headings from TOC macro

Add a new markup that allows to drop certain headings. e.g. if you write != PageTitle= this heading is not included since it is marked with a ! like we do it now to escape wikilinks, e.g. !NoWikiLink.

This seems to me an easier solution than having also a min-depth in the TableOfContents macro call like suggested on FeatureRequests/TableOfContentsMinDepth. But I haven't thought on that much... -- OliverSiemoneit 2007-01-07 21:50:36

I like the idea very much!! +1. Looking forward to see a patch for that -- DollyBuster 2007-01-07 21:50:36

Thanks Dolly. Here's a patch for the text_moin_wiki parser of Moin1.6(moin-1-6-main-7c58e8af1a97) 

   1 --- text_moin_wiki_old.py	2007-02-08 19:25:32.000000000 +0100
   2 +++ text_moin_wiki.py	2007-02-08 19:40:06.000000000 +0100
   3 @@ -88,6 +88,7 @@
   4  (?P<indent>^\s+)
   5  (?P<tableZ>\|\| $)
   6  (?P<table>(?:\|\|)+(?:<[^>]*?>)?(?!\|? $))
   7 +(?P<esc_heading>^\s*!(?P<esc_hmarker>=+)\s.*\s(?P=esc_hmarker) $)
   8  (?P<heading>^\s*(?P<hmarker>=+)\s.*\s(?P=hmarker) $)
   9  (?P<interwiki>[A-Z][a-zA-Z]+\:(%(q_string)s|([^\s'\"\:\<\|]([^\s%(punct)s]|([%(punct)s][^\s%(punct)s]))+))?)
  10  (?P<word>%(word_rule)s)
  11 @@ -745,6 +746,8 @@
  12          else:
  13              return self.formatter.text(word)
  14  
  15 +    def _esc_heading_repl(self, word):
  16 +        return self._heading_repl(word.strip(' !'))
  17  
  18      def _heading_repl(self, word):
  19          """Handle section headings."""
  20 @@ -894,7 +897,7 @@
  21          """ Replace match using type name """
  22          result = []
  23          for type, hit in match.groupdict().items():
  24 -            if hit is not None and not type in ["hmarker", ]:
  25 +            if hit is not None and not type in ["hmarker", "esc_hmarker" ]:
  26  
  27                  ##result.append(u'<span class="info">[replace: %s: "%s"]</span>' % (type, hit))
  28                  # Open p for certain types

text_moin_wiki.diff

With the markup != Your Title = you can now escape a heading from being included in the table of contents. Of course this works for headings of all levels and does also work with the IncludePage macro.. So you can do for example something like this: 

!= TaskPlanner =

[[TableOfContents]]

= Installation =
sdfsdsdfd
sdfsdf

== Step 1 ==
sfsdfsddff

== Step 2 ==
sfsasfddfa

!== Step 3 is escaped if you find that makes sense (I don't think so) ==
sdfsdfsdf


= Related Work =

Output:

screenshot.png

-- OliverSiemoneit 2007-02-08 19:15:11

New macro to produce a pagetitle

Here's a small macro that allows to create a pagetitle with '<h1 class="title">Page Title</h1>' 

   1 # -*- coding: iso-8859-1 -*-
   2 """
   3     MoinMoin - Title Macro
   4 
   5     This very complicated macro produces a page title
   6 
   7     @copyright: 2007 by Oliver Siemoneit
   8     @license: GNU GPL, see COPYING for details.
   9 """
  10 
  11 Dependencies = []
  12 
  13 def execute(macro, args):
  14     kw = {}
  15     kw['class'] = 'title'
  16     result = "%s%s%s" % (macro.formatter.heading(1, 1, **kw),
  17                          macro.formatter.escapedText(args),
  18                          macro.formatter.heading(0, 1, **kw))
  19     return ''.join(result)
  20

title.py

Advantages:

Disadvantage:

TOC macro changed to ignore text before

Here's a patch for the toc macro which makes toc forget about all the headings written before the toc macro in the raw text 

   1 --- tableofcontents_old.py	2007-02-17 22:28:02.000000000 +0100
   2 +++ tableofcontents.py	2007-02-17 22:42:46.000000000 +0100
   3 @@ -76,7 +76,10 @@
   4          self.result.append(self.macro.formatter.escapedText(_('Contents')))
   5          self.result.append(self.macro.formatter.paragraph(0))
   6  
   7 -        self.process_lines(self.pre_re.sub('', self.macro.parser.raw).split('\n'),
   8 +        # Ignore headings before toc macro
   9 +        strip_raw = self.macro.parser.raw[self.macro.parser.raw.find('[[TableOfContents'):]
  10 +
  11 +        self.process_lines(self.pre_re.sub('', strip_raw).split('\n'),
  12                             self.macro.formatter.page.page_name)
  13          # Close pending lists
  14          for i in range(self.baseindent, self.indent):

tableofcontents.diff

Advantages:

Disadvantages

CategoryFeatureRejected

MoinMoin: FeatureRequests/ExcludeHeadingsFromTableOfContent (last edited 2010-01-15 19:27:21 by gateway)