DULGUsageOfTocPlugin < DULG

---++ How to use the Plugins.TocPlugin in the DULG web

The Plugins.TocPlugin brings order into the DULG web.  There are
however a few things to remember:

   * Each topic should start with a %<nop>SECTION0% tag.  The
     actual placement in the hierarchy should be defined by
     indentation in the WebOrder topic.
   * Each topic should have a unique name for referencing.
     Technically the name only has to be unique in a topic but
     in case we want to implement an export facility into a _single_
     HTML file one day, renaming should not be neccessary.
   * To maintain editability of single topics they should not
     get too long.  This consideration also helps in conforming
     to the next item in this list:
   * %X% Sub-topics can not span over topics right now.  Let's consider
     an example:
     %BR%
     Contents of *Topic1*:
     <verbatim>
%SECTION0{name=MainTopic}% Toplevel topic

%SECTION1{name=SubTopic}% Subtopic in Topic1
     </verbatim>
     Contents of *Topic2*:
     <verbatim>
%SECTION0{name=TopLevelTopic}% Toplevel in Topic2
     </verbatim>
     Contents of *<nop>WebOrder*:
     <verbatim>
   * Topic1
      * Topic2
     </verbatim>
     This construction *will not work as expected* because
     the *Subtopic in Topic1* and the *Toplevel in Topic2* are
     (implicitely by indentation in <nop>WebOrder) in the same
     topic hierarchy level and therefore this level spans across
     two topics.
     %BR%
     A possible cure for the situation is to move *Subtopic in Topic1*
     to its own topic and include it in <nop>WebOrder at the same
     indentation as *Topic2*.
     %BR%
     %I% This quirk is the reason for topics in the DULG web containing
     only a heading.

%I% Whenever in doubt on how to use the %<nop>SECTION% tag, try to find
a similar already existing part of the documentation and study its usage
there.  Remember that the TWiki search can search for tags, so searching
for "%<nop>REF" finds usages of the %<nop>REF% tag.
You might save some time doing this instead of going for the
trial-and-error method.

-- Main.DetlevZundel - 07 Aug 2003