gnote 3.18.1-1 / usr / share / help / sl / gnote / gnote-addin-tableofcontents.page

<?xml version="1.0" encoding="utf-8"?>
<!--
      "Table of Contents" is a Note add-in for Gnote.
      It lists a note's table of contents in a menu.

      Copyright (c)  2013  Luc Pionchon <pionchon.luc@gmail.com>

      Permission is granted to copy, distribute and/or modify this document
      under the terms of the GNU Free Documentation License, Version 1.1
      or any later version published by the Free Software Foundation;
      with no Invariant Sections, with no Front-Cover Texts, and with no
      Back-Cover Texts.
      FIXME: does the statement have to show in the rendered document?

      A copy of the license is included in the section entitled "GNU
      Free Documentation License".
      FIXME: is this true? Is there a (GNOME? Yelp?) common GFDL topic?
-->
<page xmlns="http://projectmallard.org/1.0/" type="topic" id="addin-tableofcontents" xml:lang="sl">

  <info>
    <revision status="candidate" pkgversion="gnote-addin-tableofcontents-version-1.0.0"/>
    <!-- Status:
      stub        contains little to no real content
      incomplete  outline of all information, but lacking content
      draft       all content available, but unpolished
      review      ready to be reviewed by editors
      candidate   reviewed and awaiting a final approval
      final       approved and ready for publication or distribution
      outdated    was once complete or nearly complete, but needs to be revised to reflect changes

      Other possible attributes:
      version=""        revision version
      docversion=""     enclosing document
      date="2011-03-08" revision date
    -->
    <license href="http://www.gnu.org/licenses/fdl-1.1.html"><p>
      This <em>help topic</em> is licensed under the
      <link href="http://www.gnu.org/licenses/fdl-1.1.html">
        GNU Free Documentation License, Version 1.1</link> (GFDL).
      It means that you are free to copy, distribute and/or modify this document, under some conditions.
    </p>
    </license>

    <credit type="author copyright">
      <name>Luc Pionchon</name><email>pionchon.luc@gmail.com</email><years>2013</years></credit>
    <credit type="editor">
      <name>Adam Dingle</name>
      <email>adam@yorba.org</email>
      <years>2013</years>
    </credit>
    <credit type="editor">
      <name>Aurimas Cernius</name>
      <email>aurisc4@gmail.com</email>
      <years>2013,2014</years>
    </credit>
    <!-- Credit type: (can have several types)
      author        somebody responsible for writing content
      editor        somebody who has provided reviews or editorial corrections
      copyright     a person or entity which holds copyright on the work
      maintainer    the person or entity currently responsible for the work
      collaborator  somebody who has provided extensive rough information
      translator    somebody who has translated the work into another language
      publisher     a person or entity who distributes formatted copies

      <credit> can have a URL, for example for a publisher, using FOAF namespace:
        <page xmlns="http://xmlns.com/foaf/0.1/">http://flossmanuals.net/</page>
    -->

    <link type="guide" xref="index#advanced"/>
    <link type="guide" xref="editing-notes#note-content"/>
    <link type="topic" xref="addins-preferences"/>
    <link type="topic" xref="searching-notes"/>
    <desc>Navigate long structured notes</desc>
  </info>


<title>Adding a Table of Contents</title>

<desc><em>Navigate long structured notes</em></desc>

<note><p>
  This is a plugin to <app>Gnotes</app>.
  When this plugin is installed,
  there is a <gui>Table of Contents</gui> entry in the <gui>actions</gui> menu.
  See  <link xref="addins-preferences"/> to learn how to activate a plugin.
</p></note>


<section id="nutshell"><title>In a nutshell</title>

<list type="numbered">
  <item>
    <p>A heading is a full line of text, formatted with <gui>Bold+Huge</gui> or <gui>Bold+Large</gui>.</p>
  </item>
  <item>
    <p>Set headings with
       <keyseq><key>Ctrl</key><key>1</key></keyseq> or <keyseq><key>Ctrl</key><key>2</key></keyseq>.
    </p>
  </item>
  <item>
    <p>Open the table of contents with <keyseq><key>Ctrl</key><key>Alt</key><key>1</key></keyseq>, and jump to any heading.</p>
  </item>
</list>

</section>

<section id="screenshot"><title>Screenshot</title>
    <figure>
      <title>A structured note with its table of contents</title>
        <media type="image" src="figures/gnote-addin-table-of-contents.png" mime="image/png">
        </media>
    </figure>
</section>


<section id="navigating"><title>Navigating through long notes</title>

<p>
A long note may become difficult to navigate.
It is then natural to structure the note by
marking sections and subsections with headings.
</p>

<p>
This plugin makes it easy to navigate through long structured notes.
Once you have set headings in your note,
the table of contents of the note will show in actions menu.
Then you can jump directly from the menu to any heading.
</p>

</section>


<section id="setheadings"><title>Structuring your notes with headings</title>

<p>
A heading is simply a complete line with specific text formatting:
</p>
<list>
  <item><p>Level 1 headings, for sections, are lines formatted with a <gui>Bold+Huge</gui> font.</p></item>
  <item><p>Level 2 headings, for subsections, are lines formatted with a <gui>Bold+Large</gui> font.</p></item>
</list>


<p>To format a heading line, either:</p>

<list>
  <item>
    <p>Use the commands <gui>Heading 1</gui> and <gui>Heading 2</gui>
       in the <guiseq><gui>Actions</gui><gui>Table of Contents</gui></guiseq> menu.</p>
  </item>

  <item>
    <p>Use the keyboard shortcuts <keyseq><key>Ctrl</key><key>1</key></keyseq>
    and <keyseq><key>Ctrl</key><key>2</key></keyseq> for headings of level 1 and 2.</p>
 </item>
</list>

<note><p>
  These commands apply the formatting to the complete line.
  You don't need to select it first.
  It is enough if the cursor is on the line.
</p><p>
  Alternatively, with the cursor on a new line, activate the heading command and then enter the heading title.
</p></note>

<p>You can even use the normal formatting commands from the <gui>Text</gui> menu:
    <gui>Bold</gui>, <gui>Large</gui> and <gui>Huge</gui>, and their respective keyboard shortcuts.
    If, for example, your line is already formatted as <gui>Huge</gui>, then you just need to make it also <gui>Bold</gui> to turn it into a heading 1.
    See <link xref="editing-notes"/> to learn how to set text styles.
</p>

</section>


<section id="showtable"><title>Showing the table of contents</title>

<p>You can access the table of contents either:</p>
<list>
<item><p>In the menu <guiseq><gui>Actions</gui><gui>Table of Contents</gui></guiseq>.</p></item>
<item><p>In <guiseq><gui>context menu</gui><gui>Table of Contents</gui></guiseq> (right-click on the note window).</p></item>
<item><p>In a <gui>popup menu</gui>, with the keyboard shortcut <keyseq><key>Ctrl</key><key>Alt</key><key>1</key></keyseq>.</p></item>
<p>Then you can navigate up and down with the arrow keys and jump to the selected heading with <key>enter</key>. Or just click with your mouse on the heading to jump to.</p>
</list>

</section>


<section id="troubleshooting"><title>Troubleshooting</title>
<terms>
  <item><title><em style="strong">One heading does not show in the table of contents</em></title><p>
    There might be some characters in the heading line, such as whitespace characters, which are not formatted as a heading. Make sure that <em>the whole line</em> is formatted as a heading. See <link xref="#setheadings"/>.</p>
  </item>
  <item><title><em style="strong">There is an empty line in the table of contents</em></title><p>
    An empty line, possibly including whitespaces, is formatted as a heading. Jump to this line and delete the area.</p>
  </item>

  <item><title/><p>
  </p>
  </item>

</terms>

</section>

</page>