Advanced menu theming in Drupal 7 I've cruised around the web and it is not at all obvious how to theme custom menus.  I've looked for hours and have not found one single post that illustrates the process, from start to finish, of creating a menu and customizing its output.  It seems like this is a multi-stage process:


Create the menu through the Drupal interface.
Create a theme function in your template.php file to theme the output.
Expose this menu to a template file (somehow) by adding it as a variable.
Call the theme function on the menu in the template file.


1 is easy enough to do, the problems I run into are with 2, 3, and 4.  Looking at the default page template, I see that it exposes the main menu in the variable $main_menu.  Later down the page you can see the function theme('links__system_main_menu', array('links' =&gt; $main_menu..., which means it's looking for an appropriately named theme function somewhere and using it to generate the output.

I know if I place function theme_links__system_main_menu(&amp;$variables) {...} in my template.php file Drupal will use that function as opposed to function theme_menu_links(&amp;$variables) {...}.

What I don't know is how Drupal links the custom menu I created with that function.  Let's say for example that I created a menu called My Menu.  Could I create the following function in my template.php file and theme the output for that menu? function theme_links__system_my_menu(&amp;$variables) {...}

Also, how does one make that custom menu available to a template file?  How does Drupal expose the $main_menu variable to page.tpl.php?

I think the key I'm missing here is how to embed the variable that represents my custom menu into a template page.  For the most part though I'm completely lost with what to do after having created the menu.

Thanks for the help.

EDIT: Probably should post what I'm doing.  Per my comment to BetaRide below, I need to inject customized HTML into the &lt;li&gt; elements of the menu items. Specifically, I'm adding Twitter Bootstrap icons.
Drupal's implementation of menus is a bit special, It doesn't always work the way it seems it should. 

You can take a look at the core implementation of template_preprocess_page() to how the Main Menu links are added as a variable to the page template. You have to drill down a bit in the API docs, but the function you want to call in your implementation of theme_preprocess_page() is menu_navigation_links(), which will return an array of links in the menu.

Looking at line 106 of Drupal core's page.tpl.php file, you can see how the main menu links are themed in the template by calling the theme() function with a hook of 'links__system_main_menu'.  

Theoretically, this implementation should be able to be duplicated with a custom menu by following the standard naming conventions. So, in template.php, you could have:

function THEMENAME_preprocess_page(&amp;$variables){
  $variables['custom_menu'] = menu_navigation_links('menu-custom-menu');
}

function THEMENAME_links__menu_custom_menu(&amp;$variables){
 //custom theme function here
}


and in page.tpl.php, you would add something like this:

&lt;?php print theme('links__menu_custom_menu', array('links' =&gt; $custom_menu, 'attributes' =&gt; array('id' =&gt; 'custom-menu', 'class' =&gt; array('links', 'inline', 'clearfix')), 'heading' =&gt; t('Custom menu'))); ?&gt;


However, adding the custom menu as a variable on your page template is not necessary. You could easily place the custom menu's block into a desired region via the Drupal admin interface.  Also, you could change the site's settings for the Main Menu source, effectively replacing the default $main_menu variable in page.tpl.php with your custom menu. 

EDIT: I am just seeing your addition about your end goal being to just add some custom html to the menu items for icons. Depending on how you are adding these icons, there are a couple different Drupal module options.

Menu Icons - allows you to upload an image via the Menu item's settings and automatically generates CSS (customizable via a template) that adds the image as a background on the menu item. 

Menu Attributes - allows you to add a custom class to each menu item via its settings in the admin. Once a unique class is added to each menu item, you could use CSS to add an icon to the menu item or use javascript to inject the additional HTML into the menu item.