**<<doctool>> markup**
To add a page written in [doctools] to the Wiki, you have the following options:

   * Type it in again using Wikit markup
   * Convert it to Wikit markup using the [doctools] to Wiki converter
   * Add the page written in [doctools] markup to the Wiki surrounded by `<<doctool>>` lines

Changes within the `<<doctool>>` blocks are only visible in word compares, not in line compares and edit summary.

Here below the [menubar - A command that creates menubar objects%|%menubar] man page is included using the `<<doctool>>` markup.

**Manpage**
----
<<doctool>>
[comment {-*- tcl -*- doctools manpage}]
[manpage_begin menubar n 0.5]

[copyright "2009 Tom Krehbiel <krehbiel.tom@gmail.com> All rights reserved."]

[titledesc "Creates an instance of the [emph menubar] Class."]
[moddesc   {Create and manipulate a menubar}]

[require Tcl 8.6]
[require Tk 8.6]
[require menubar [opt 1.0]]

[description]

[list_begin definitions]
[call [cmd {menubar new}]  [opt options]]
[list_end]

[para] 
Create and return a new instance of the menubar class. The
menubar class encapsulates the definition, installation and
dynamic behavior of a menubar. The class doesn't depend on a
widget framework and therefore can be used with or without a
frameworks (e.g. Bwidget, IWidget, Snit, etc.). Unlike other Tk
widget commands, the menubar command doesn't have a [emph pathName]
argument because it is a feature of the display manager and not a
Tk widget.

[section {STANDARD OPTIONS}]

The following standard options can be used when creating a
menubar instance. The effect of these options is platform
specific.

[list_begin options]
[opt_def [uri http://docs.activestate.com/activetcl/8.5/tcl/TkCmd/options.htm#M-activebackground -activebackground]]
[opt_def [uri http://docs.activestate.com/activetcl/8.5/tcl/TkCmd/options.htm#M-activeborderwidth -activeborderwidth]]
[opt_def [uri http://docs.activestate.com/activetcl/8.5/tcl/TkCmd/options.htm#M-activeforeground -activeforeground]]
[opt_def [uri http://docs.activestate.com/activetcl/8.5/tcl/TkCmd/options.htm#M-background -background]]
[opt_def [uri http://docs.activestate.com/activetcl/8.5/tcl/TkCmd/options.htm#M-borderwidth -borderwidth]]
[opt_def [uri http://docs.activestate.com/activetcl/8.5/tcl/TkCmd/options.htm#M-cursor -cursor]]
[opt_def [uri http://docs.activestate.com/activetcl/8.5/tcl/TkCmd/options.htm#M-disabledforeground -disabledforeground]]
[opt_def [uri http://docs.activestate.com/activetcl/8.5/tcl/TkCmd/options.htm#M-font -font]]
[opt_def [uri http://docs.activestate.com/activetcl/8.5/tcl/TkCmd/options.htm#M-foreground -foreground]]
[opt_def [uri http://docs.activestate.com/activetcl/8.5/tcl/TkCmd/options.htm#M-relief -relief]]
[list_end]

[section INTRODUCTION]

[para]

An instance of the menubar class provides methods for compiling a
description of the menubar, configuring the items in the menu and 
installing the menubar in toplevel windows.

A menubar can be thought of as a tree of cascading menus. Users define
a menubar using a language that results in a human readable description
of a menubar. The description of the menubar is then compiled by an
instance of the menubar class and can then be installed in one or more
toplevel windows.

By default a menubar instance is kept syncronized in all toplevel
windows where it is installed which means the state of radio buttons,
checkboxs, etc. are the same for all installed toplevel windows.

The menubar class provides many unique capabilities that are not
found in other tcl/tk menubar implementation. Some of these are:

[list_begin itemized]
[item] A tagging system that simplifies access to menu entries in the menu tree.
[item] Automatic management of state variables for checkbuttons and radiobuttons.
[item] Namespace support for all callback commands so callback commands can be easily grouped into namespaces.
[item] Support for menubar syncronization across multiple toplevel windows.
[item] A simplifed and uniform interface for all callback commands.
[item] A simplified method for creating radio buttons.
[item] Support for hidding and exposing menu items on the menubar.
[item] Support for user defined tags that depend on the toplevel window context.
[item] Management of tearoff menus.
[item] Support for user defined menu entries.
[item] Support for saving and restoring user defined menu entries.
[list_end]

[section TERMINOLOGY]

[list_begin definitions]

        [def MENUBAR]

        The visible rendering of a menubar in a toplevel window is a horizontally
        group of cascading Tk menus.

        [def MENU]

        A menu is an ordered list of items that is rendered
        vertially. Menus are not visible until a user
        preforms some action (normally a <ButtonPress-1> event). A menu
        may contain any number of child menu's that are rendered as
        cascading menus. Cascading menus are rendered next to the parent menu
        when they are activated.

        [def {MENU ENTRY}]

        A menu contains an ordered list of items called menu entries.
        Menu entries have a type and the menubar class supports the
        following 6 entry types: 
        [emph Command], [emph Checkbutton], [emph Radiobutton], [emph Separator], [emph Group] and [emph Menu]. 

        [def {ENTRY LABEL}]

        Each menu entry has a visible string that is called the entry label.

        [def {TAGS}]

        Tags are names that are used when refering to items in the menu
        tree or window. A tag name is an alphanumeric character string
        that may include the underscore character. Menu tree tags are
        defined for all nodes and leafs in a menu tree. This provides a
        flat abstraction of the tree and simplifies item referancing in
        the menubar methods. Without this abstraction it would be
        necessary to reference menu elements using a tree path which
        could change at runtime. The menubar class also has a method that
        can create a user defined tag that are window dependent. User
        defined tags store values that change based on the currently
        active toplevel window. These tags can store widget pathnames for
        use by callback code so that output can be routed to the
        appropreate toplevel window.

[list_end]

[section METHODS]

[list_begin definitions]

        [call [arg mBarInst] [cmd define] [arg body]]

        Compiles [emph body] into a tree of menu entries which define the 
        visual layout of the menubar. The [emph body] argument 
        describes the layout using the following syntax where the
        elements of the syntax are described below.

        [para]
        [emph {body == definitions}]

[example_begin]
definitions ::= { <ignore> | <definition> | <definition> <definitions> }
ignore      ::= { <nl> | <white-space> <nl> | # <comment> <nl> }
definition  ::= { <command> | <checkbutton> | <radiobutton> | <separator> | <group> | <menu> }
command     ::= <label> C <tag> <nl>
checkbutton ::= <label> X { <tag> | <tag>+ } <nl>
radiobutton ::= <label> R { <tag> | <tag>+ } <nl>
separator   ::= <dummy> S <tag> <nl>
group       ::= <dummy> G <tag> <nl>
menu        ::= <label> { M:<tag> | M:<tag>+ } <nl> <definitions>
[example_end]

        [emph { }]

        [list_begin definitions]

        [def {C - Command}] 
        The command entry is the most common type of entry. This entry
        behaves much like a Tk button widget.

        [def {X - Checkbutton}] 
        A checkbutton entry behaves much like a Tk checkbutton
        widget. When it is invoked it toggles back and forth between
        a selected and deselected states. The value of a checkbutton
        is a boolean (i.e. 1 or 0). By default all checkbuttons are
        deselected. If you want the checkbutton to be initially selected
        then include a trailing plus (+) with the tag name.

        [def {R - Radiobutton}] 
        A radiobutton entry behaves much like a Tk radiobutton widget. A
        radiobutton entries is a member of a radiobutton group that
        controls the behavior of the radiobuttons in the group. All
        radiobuttons in a group are given the same tag name. In the
        example below Red, Green and Blue all have the same tag and are
        therefore all in the same radio button group. The trailing plus
        (+) on Red's tag will cause Red to be the initally select item in
        the group.

        [def {S - Separator}] 
        A separator is an entry that is displayed as a horizontal
        dividing line. A separator may not be activated or invoked, and
        it has no behavior other than its display appearance. The
        label and tag value for a separator are ignored.

        [def {G - Command Group}] 
        The list type menu entry marks a location in the menu tree where
        a menu can be dynamically extended with new entries. Extention is
        only allowed at the end of a menu so only one L type entry can
        exist per menu and it must be the last item on the menu. The L
        type entry is rendered as a seperator line. The [emph item]
        subcommand is used to manipulate list entries.

        [def {M - Menu}] 
        An M type entry is used to define both menubar menus and cascading
        menus. Menu entries are the most complicated of the 6 menu types.
        A menu entry is composed of three list element. The first element
        of the list is its label. The second element of the list is a
        composite string consisting of a type identifier (M) followed by
        an optional tag (beginning with a ':' seperator) and finally an
        optional plus (+) which indicates that the menu is a tearoff
        menu. The final element of the list is a LIST VALUE.

        [list_end]
        
[list_end]


[list_begin definitions]

        [call [arg mBarInst] [cmd install] [arg {pathName body}]]

        The [emph install] method installs the menubar created with the
        [emph define] method into toplevel window [emph pathName]. The
        [emph body] argument of the command contains a tcl script which
        is used to initialize the installed menubar. Normally the tcl
        script will contain calls to various menubar methods to perform
        the initialization. The initialization code is only run once
        when the menubar is installed. The namespace in which the [emph install] 
        method is executed becomes the default namespace for callback commands
        (see [emph menu.namespace] below for more details).

[list_end]


[list_begin definitions]
        [call [arg mBarInst] [cmd menu.configure] [arg {option tag-settings ?option tag-settings ...?}]]

                Configures the tags of a menubar and returns an empty string. This method provides a convinient
                way to configure a larger number of tags without the verbosity of using the [emph tag.configure] method.

                [list_begin definitions]

                [def [arg {option}]]
                        [emph Option] may have any of the values accepted by the [emph tag.configure] method.

                [def [arg {tag-settings}]]
                        The [emph {tag-settings}] argument is a string that is converted to a list of tag-value pairs
                        useing the following syntax.

                        [para]
                        Syntax for [emph tag-settings].

[example_begin]
tag-settings ::= { <ignore> | <value> | <value> <tag-settings> }
ignore       ::= { <nl> | <white-space> <nl> | # <comment> <nl> }
value        ::= <tag> <option-value> <nl>
[example_end]

                [list_end]

[list_end]


[list_begin definitions]

        [call [arg mBarInst] [cmd menu.namespace] [arg {tag namespace}]]

                Change the namespace for a subtree of the menubar
                starting at entry [emph tag]. The new value will be [emph namespace]. 
                Each entry in the menubar tree has an
                associated namespace which will be used for its callback
                procedure. The default namespace is the namespace where
                the [emph install]  method was executed. The [emph namespace] 
                method can be used to change the namespace
                that will be used for callbacks in a subtree of the
                menubar. This method can only be used in the context of
                an [emph install] script.

[list_end]

[list_begin definitions]

        [call [arg mBarInst] [cmd menu.show] [arg tag]]
        [call [arg mBarInst] [cmd menu.hide] [arg tag]]
        
                Shows or hides [emph tag] menubar menu. By default when a
                menubar tree is defined all entries are visible to the user.
                These two methods can be used to control visiblity of menubar
                menus. The [emph hide] methods can be used in the
                context of an [emph install] script so that a menu is
                initially hidden when an application is started.

[list_end]

[list_begin definitions]

        [call [arg mBarInst] [cmd tag.add] [arg {tag value}]]
        
                Add a user defined [emph tag] value. The [emph tag.add] method
                adds a new tag-value pair to the the tags defined for a
                menubar. User defined tags are different from the tags
                created by the [emph define] method. The [emph tag.add]
                method can only be used in an [emph install] script and its
                value is associated with the toplevel where the menubar is
                installed. This makes the tag context sensitive so callback
                code that queries the tag value will receive a value that
                is associated with the window that performed the callback.

[list_end]

[list_begin definitions]

        [call [arg mBarInst] [cmd tag.configure] [arg {pathName tag ?option value ...option value?}]]

                Given the [emph pathName] of a toplevel window and a [emph tag] this method configures the
                menu entry associated with the tag and return an empty string. 

                        [list_begin definitions]

                        [def [arg {Standard Options}]]
                        
                        These option are the same as those described for menu entries in the Tk [emph menu] documentation.
                        
                        [list_begin options]
                        [opt_def -activebackground]
                        [opt_def -activeforeground]
                        [opt_def -background          ]
                        [opt_def -bitmap                  ]
                        [opt_def -columnbreak          ]
                        [opt_def -compound                  ]
                        [opt_def -font                          ]
                        [opt_def -foreground          ]
                        [opt_def -hidemargin          ]
                        [opt_def -image                   ]
                        [opt_def -indicatoron          ]
                        [opt_def -label                   ]
                        [opt_def -selectcolor          ]
                        [opt_def -selectimage          ]
                        [opt_def -state  ]
                        [list_end]

                        [emph { }]

                        [def {Class Specific Options}]
                        
                        [list_begin options]
                        [opt_def -bind {{uline accel sequence}}]
                        The value of the [emph -bind] option is three element list where the values are as follows.
                        
                        [list_begin definitions]
                        [def {uline}] 
                          An integer index of a character to underline in the entry.
                          This value performs the same function as the Tk [emph menu] -underline option.
                          If this value is an empty string then no underlineing is performed.
                        [def {accel}] 
                          A string to display at the right side of the menu
                          entry. The string normally describes an accelerator keystroke sequence that
                          may be typed to invoke the same function as the menu entry.
                          This value performs the same function as the Tk [emph menu] -accelerator option.
                          If this value is an empty string then no accelerator is displayed.
                        [def {sequence}] 
                          A bind sequence that will cause the entries associated command to fire.
                        [list_end]

                        [opt_def -command {cmdprefix}]
                          The value of the [emph -command] option a command
                          prefix that is evaluated when the menu entry is invoked.
                          By default the callback is evaluate in the
                          namespace where the [emph install] method was executed. Additional values
                          are appended to the [emph cmdprefix] and are thus passed to the
                          callback command as argument. These additional arguments are discribed
                          in the list below.

                        [list_begin definitions]
                        [def {command entry}]
                          1) The pathname of the toplevel window that envoked the callback.
                        [def {checkbutton entry}]
                          1) The pathname of the toplevel window that envoked the callback.
                          [para]
                          2) The checkbutton's tag name
                          [para]
                          3) The new value for the checkbutton
                        [def {radiobutton entry}]
                          1) The pathname of the toplevel window that envoked the callback.
                          [para]
                          2) The radiobutton's tag name
                          [para]
                          3) The label of the button that was selected
                        [def {group entry}]
                          1) The pathname of the toplevel window that envoked the callback.
                        [list_end]

                        [opt_def -sync {{yes | no}}]
                          The [emph -sync] option can only be configured
                          in the context of an [emph install] script and will only effects the behavior of
                          checkbutton and radiobutton entries. When the value is
                          'yes' the internal value of the menu entry is the same 
                          across all installed toplevel windows. When the value is 'no'
                          each toplevel window will have a seperate internal value for the entry.

                        [list_end]

                [list_end]

[list_end]

[list_begin definitions]

        [call [arg mBarInst] [cmd tag.cget] [arg {pathName tag ?option?}]]
        
        Returns the value of the configuration option given by [emph option]
        or the value of a user defined tag. The option argument may be any
        of the options accepted by the [emph tag.configure] method for the
        [emph tag] type. User defined tags are queried without an [emph option]
        value.

[list_end]

[list_begin definitions]

        [call [arg mBarInst] [cmd group.add] [arg {tag label ?cmd? ?accel? ?sequence? ?state?}]]
        
        Add a command to the group with tag name [emph tag]. This method
        appends a new command entry to the end of a command group. The order of the
        arguments is fixed but arguments to the right can be ignored. Arguments to
        this method have the following meaning.
        
        [list_begin arguments]
        [arg_def tag (string)]                The tag name of the command group.
        [arg_def label (string)]        The displayed label for the menu entry.
        [arg_def cmd (string)]                A command prefix that will be used for callback command.
        [arg_def accel (string)]        An accelerator string that will be displayed next to the entry label.
        [arg_def sequence (string)]        A bind sequence that will be bound to the callback command. 
        [arg_def state (enum)]                Sets the active state of the command. One of:  normal, disabled, active
        [list_end]
        
[list_end]

[list_begin definitions]

        [call [arg mBarInst] [cmd group.delete] [arg {tag label}]]
        
        Delete a command from a group with tag name [emph tag]. This method
        deletes command [emph label] from a command group.

[list_end]

[list_begin definitions]

        [call [arg mBarInst] [cmd group.move] [arg {direction tag label}]]
        
        Change the position of an entry in a group with tag name [emph tag].
        The [emph direction] argument is the direction ('up' or 'down') the
        entry will be move. The entry that is moved has the name [emph label].

[list_end]

[list_begin definitions]

        [call [arg mBarInst] [cmd group.configure] [arg {tag label ?option value ...option value?}]]
        
        Configure the options of an entry in the command group with
        tag name [emph tag]. This method is similar to the [emph tag.configure] 
        method except that it works on entries in a command group. Set documentation 
        for the [emph tag.configure] method (above) for more details on command
        entry options.

[list_end]

[list_begin definitions]

        [call [arg mBarInst] [cmd group.serialize] [arg {tag}]]
        
        Return a string serialization of the entries in a command group. The
        argument [emph tag] is the tag name for the group that is to be serialized.
        The resulting serialization is a list containing three
        element  (1) the tag name of the group  (2) a dictionary
        containing group level options (3) a list of zero or more similar three
        element lists that describe the entries in the group.

[list_end]

[list_begin definitions]

        [call [arg mBarInst] [cmd group.deserialize] [arg {tag stream}]]
        
        Replace the contents of group tag [emph tag] with the commands
        defined in the serialization [emph stream]. The original contents of
        the group are lost.

[list_end]

[list_begin definitions]

        [call [arg mBarInst] [cmd debug] [arg {{ tree | nodes | installs }}]]
        
        This method returns a list of lines that is a printable version
        of the internal structures used by the menubar class.

[list_end]

[section EXAMPLE]

[example_begin]
package require Tcl
package require Tk
package require menubar

set tout [lb]text .t -width 25 -height 12[rb]
pack ${tout} -expand 1 -fill both
set mbar [lb]menubar new \
    -borderwidth 4 \
    -relief groove  \
    -foreground black \
    -background tan \
    [rb]
${mbar} define {
    File M:file {
        Exit                 C      exit
    }
    Edit M:items+ {
    #   Label               Type    Tag Name(s)
    #   -----------------   ----    ---------
        "Cut"               C       cut
        "Copy"              C       copy
        "Paste"             C       paste
        --                  S       s2
        "Options" M:opts {
            "CheckList" M:chx+ {
                Coffee      X       coffee+
                Donut       X       donut
                Eggs        X       eggs
                }
            "RadioButtons" M:btn+ {
                "Red"       R       color
                "Green"     R       color+
                "Blue"      R       color
                }
        }
    }
    Help M:help {
        About               C       about
    }
}
${mbar} install . {
    ${mbar} tag.add tout ${tout}
    ${mbar} menu.configure -command {
        # file menu
        exit            {Exit}
        # Item menu
        cut             {CB Edit cut}
        copy            {CB Edit copy}
        paste           {CB Edit paste}
        # boolean menu
        coffee          {CB CheckButton}
        donut           {CB CheckButton}
        eggs            {CB CheckButton}
        # radio menu
        color           {CB RadioButton}
        # Help menu
        about           {CB About}
    } -bind {
        exit        {1 Cntl+Q  Control-Key-q}
        cut         {2 Cntl+X  Control-Key-x}
        copy        {0 Cntl+C  Control-Key-c}
        paste       {0 Cntl+V  Control-Key-v}
        coffee      {0 Cntl+A  Control-Key-a}
        donut       {0 Cntl+B  Control-Key-b}
        eggs        {0 Cntl+C  Control-Key-c}
        about       0
    } -background {
        exit red
    } -foreground {
        exit white
    }
}
proc pout { txt } {
    global mbar
    set tout [lb]${mbar} tag.cget . tout[rb]
    ${tout} insert end "${txt}\n"
}
proc Exit { args } {
    puts "Goodbye"
    exit
}
proc CB { args } {
    set alist [lb]lassign ${args} cmd[rb]
    pout "${cmd}: [lb]join ${alist} {, }[rb]"
}
wm minsize . 300 300
wm geometry . +4+4
wm protocol . WM_DELETE_WINDOW exit
wm title . "Example"
wm focusmodel . active
pout "Example started ..."
[example_end]


[section CAVEATS]

[para]
This implementation uses TclOO so it requires 8.6. The code has been
tested on Windows (Vista), Linux, OSX (10.4) and Solaris however on OSX
the Tk menu command doesn't behave like it does on the other platforms.
I have observed the following issues on OSX (1) the -background 
option don't work for the toplevel menubar items but does work for subitems
 (2) the -underline option
doesn't work but the {apple} key seems to have a predefined behavior
that provides some shore cuts to the commands (3) Tk key bindings don't work
(4) the -accellerator options sort of
works but the string is truncated.


[see_also [uri http://www.tcl.tk/man/tcl8.6/TkCmd/menu.htm menu]]

[manpage_end]
<<doctool>>

**Screenshots**

Some screenshot:

***Screen shot of cascade menus***

[menubar ScreenShot1]

***Screen shot of dynamic menu extension***

[menubar ScreenShot2]
----
'''[WHD] - 2009-12-09 12:19:51'''

Can something be done about the typography?  The text fonts are '''much''' bigger than what I see with normal Wiki markup; it makes it look out of place and ugly.

Still, very cool--a neat new feature.
----
'''[AK] - 2009-12-09 13:40:49'''

I believe that changing the font (sizes) is not a big problem. Jos copied the standard CSS for doctools generated HTML into the Wiki CSS when he added the doctools support. Changing these doctools-specific parts of the Wiki CSS should allow us to bring the fonts into line with Wikit's configuration.
----
'''[jdc] - 2009-12-09 15:24:43'''

This is a wiki rendering bug, where the <h2> is not properly closed. Working on it ...
----
'''[WHD] - 2009-12-09 15:32:03'''

Beautiful.