Overview

Under construction...

Markup

Nested uses a superset of a markup called txt2tags. This section is based on the oficial txt2tags documentation, created by Aurélio Jargas.

The markup used by Nested is simple and easy. But wait, it's powerful too!

You can insert images, make lists, quotes and even tables. All of that using just a few extra characters on your text. No more tag names or funky attributes to remember.

The following section is a complete guide of the marks. For a more lightweight example load in Nested:

	File > Examples > Markup

Paragraphs

Paragraphs are groups of lines delimited by blank lines. Other blocks like lists, quote, table or verbatim also ends a paragraph.

Example:

A paragraph is made by one or
more lines.

A blank line separates them.

Line breaks

Sometimes the user requires to explicitly insert a line break, this can be acomplished using the @@ tag.

Example:

| This is a @@ multiline @@ table | The other cell |
 
This is a line break in a paragraph. Lorem ipsum 
dolor sit amet, consectetur adipiscing elit. 
Phasellus semper tempus est, non pulvinar mi 
venenatis vel. @@
Phasellus consequat arcu ut ligula feugiat id 
posuere erat imperdiet. Duis vehicula, quam in 
varius fringilla, elit felis varius lorem, ut 
sagittis odio nunc id lacus.

Comments

Used to insert text that will not appear on the published document. It can also be used to deactivate (not delete) large portions of the contents. Useful for TODO and FIXME reminders and editor's notes.

Example:

% start a line with
a percent sign,
% and it will be ignored
useful for TODOs!

%%%
This is some text that I don't want 
to be shown anymore. 
This can be as large as I want.
%%%

Target comments

You can comment out some content and specific it to be shown only for some particular target. For example, if you want a link to appear only when publishing to HTML, or if you want to link to different version of your document depending on the way it is shown.

Syntax:

%target%<space>Conditional comment content

Note: The target comments avalaible are:

• HTML: %xhtmls% or %html%
• LaTeX: %tex%, %latex% or %pdf%
• Plain text: %txt% or %text%

Also, please note the trailing space after the %target%.

Example:

%html% You can download the PDF version of this document from 
%html% [my website http://www.somedomain.com/myfile.pdf]
%pdf% You can view the HTML version of this document in 
%pdf% [my website http://www.somedomain.com/myfile.html]

Beautifiers

Beautifiers can be used to format content. Nested supports seven beautifier types:

1. Bold: Bold text
2. Italic: Italic text
3. Underline: Underlined text
4. Strike: Striked text
5. Superscript: ^{Superscript text}
6. Underscript: _{Undescript text}
7. Monospace: Monospaced text

Note: The marks must be glued with the contents (no spaces): ** this ** or ** this** is invalid.

Example:

Simple beautifiers:

+ Bold: **Bold text**
+ Italic: //Italic text//
+ Underline: __Underlined text__
+ Strike: --Striked text--
+ Superscript: ^^Superscript^ ^
+ Underscript: ,,Undescript, ,
+ Monospace: ``Monospaced text``


Nested beautifiers:

+ Bold and Italic: **//Bold Italic//** 
  or //**Bold Italic**//
+ Underline and strike: 
  __--Underlined strike--__
+ Superscript and bold: 
  ^^**Superscript bold**^ ^
+ etc..

Lists

Nested supports three types of lists. All the list are written in a natural way and leading spaces define the depth.

Note: Two blank lines close all the lists. An empty item closes the current list. Lists can be mixed, like a definition list inside a numbered list.

Example:

Ordered list

- This is a list of items
- Just use hyphens
  - More indent opens a sublist


Two blank lines close all the lists.

Unordered list

+ Change the hyphen by a plus
+ And you have a numbered list
  + Same rules apply
  +
+
An empty item closes the current list.

Definition list

: Definition list
  A list with terms
: Start term with colon
  And its definition follows
:

Quotes

A block quotation (also known as a long quotation or extract) is a quotation in a written document, that set off from the main text as a paragraph, or block of text, and typically distinguished visually using indentation and a different typeface or smaller size quotation.

To insert a quotation prepend the line with the quote with a tabulation (press <Tab> key).

Example:

A quoted paragraph is prefixed
	by a TAB.
		More TABs, more deep.
No TAB or blank line, closes quote.

Verbatim

Verbatim block and lines are used to insert pre-formatted text, preserving spacing and line breaks, using a monospaced font and escaping markup and macros.

To insert a verbatim line insert 3 consecutive backquotes at the beginning of the line, followed by a space, followed by the text, ``` like this

To insert a verbatim block surround your text with 3 consecutive backquotes. See the example.

Example:

```
This **text** will not be interpreted
  and    //spacing// and line breaks
    will    remain the   same.
%%date
```

This line will be interpreted.
``` But this line won't.

This **text** will not be interpreted
  and    //spacing// and line breaks
    will    remain the   same.
%%date

But this line won't.

Math block

A math block is a special type of block for documenting mathematical formulas.

On HTML target mathematical formulas rendering is supported by a stripped down version of the MathJax library and on LaTeX/PDF targets support is provided natively. If you want formulae rendering on HTML target please check that the mathjax library is included in your HTML libraries when publishing to that target. If that library is not included your code blocks will be shown as traditional <p> blocks.

Nested includes a helper button for an easy way to include formulas (it insert an example code). That button will automatically include the MathJax library to the document libraries when used.

For an extensive example on how to use the math block open in Nested:

	File > Examples > Math

Syntax:

<<<
<math lines>
>>>

Example:

Let's assume you're writting a Math book:

The Cauchy-Schwarz Inequality
<<<
\[
\left( \sum_{k=1}^n a_k b_k \right)^{\!\!2} \leq
 \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)
\]
>>>

An Identity of Ramanujan
<<<
\[
   \frac{1}{(\sqrt{\phi \sqrt{5}}-\phi) e^{\frac25 \pi}} =
     1+\frac{e^{-2\pi}} {1+\frac{e^{-4\pi}} {1+\frac{e^{-6\pi}}
      {1+\frac{e^{-8\pi}} {1+\ldots} } } }
\]
>>>

Code block

A code block is a special type of block for documenting computer instructions or programming code.

On HTML target syntax highlight is supported by the SyntaxHighlighter library and on LaTeX/PDF targets support is provided by the listings package. If you want syntax highlight on HTML target please check that the syntaxhighlighter library is included in your HTML libraries when publishing to that target. If that library is not included your code blocks will be shown as traditional <pre> blocks. listings package is unthemed by default, check File > Examples > Code for a complete example on how to theme the listings package via the LaTeX header.

Nested includes a helper dialog for an easy way to include code. That dialog will automatically include the SyntaxHighlighter library to the document libraries when used.

Syntax:

{{{ code
<code lines>
}}}

Note: Code must be one of the following: as3, bash, cf, csharp, cpp, css, delphi, diff, erlang, groovy, javascript, java, javafx, perl, php, plain, powershell, python, ruby, scala, sql, vb or xhtml.

Example:

Let's assume you're writting a Python book:

Ok, let's write our first Python program. First, open a terminal and 
launch the Python interpreter:

{{{ bash
user@computer:~$ python
}}}

Then, write the following:

{{{ python
$$$ print('Hello World')
Hello World
}}}

To find out what python interpreters do you have type:

{{{ bash
user@computer:~$ ls -lah /usr/bin/ | grep python

lrwxrwxrwx  1 root   root        9 2011-11-12 12:34 python -> python2.7
-rwxr-xr-x  1 root   root     2,7M 2011-10-04 15:26 python2.7
}}}

user@computer:~$ python

$$$ print('Hello World')
Hello World

user@computer:~$ ls -lah /usr/bin/ | grep python

lrwxrwxrwx  1 root   root        9 2011-11-12 12:34 python -> python2.7
-rwxr-xr-x  1 root   root     2,7M 2011-10-04 15:26 python2.7

Tagged

Nested supports the inclusion of target code in case your document requires some tunning that can only be accomplished using target code. As you might infer, this feature nicely complements target comments.

Target code can be inserted inline, per line or in a block. To include target code inline enclose the target code with 2 single quotes '', to include a whole line as target code prepend the line with 3 single quotes ''' and to include several lines as target code enclose those lines with 3 single quotes.

Example:

%html% ''' 
%html% <div style="text-align: right;">
%html% <!-- This is a HTML comment -->
%html% '''

A tagged area is enclosed
inside three single quotes.

No ''<span style="color:red;">**parsing**</span>''
is made inside it, useful to insert target code.

%html% ''' </div>

Tables

Nested supports the insertion of tables to present tabular data. Table syntax is very flexible and powerfull, these are the rules:

• A leading pipe "|" identifies a table row.
• A leading double pipe "||" identifies a table title row.
• Leading spaces before first pipe identifies table centered align.
• The fields are separated by the " | " string (space pipe space).
• A final pipe "|" at the first table row sets visible borders.
• A final pipe "|" at the other table rows are ignored (just cosmetic).
• Closing a cell with more than one pipe "|" identifies column span: "||" for 2 columns, "|||" for 3 and so on.
• Natural spaces inside each cell identifies its alignment.

Example:

To create a table, separate the cells with a | character. Like this:

| This  | is   | a simple |
| table | cell | cell     |

If you want the first row of the table to be the table heading, just add two | characters at the beginning of that line. Like this:

|| Element  | Symbol |
 | Hydrogen | H      |
 | Helium   | He     |
 | Lithium  | Li     |

Now, let's change some options of the previous table, now we want it centered (note the leading space on the first line) and without a border (note the missing pipe at the end of the first line).

 || Element | Symbol
 | Hydrogen | H      |
 | Helium   | He     |
 | Lithium  | Li     |

Now, let's create a more complex example using column span:

 ||        Monday menu        |||
  |       __Breakfast__       |||
  |  Food   |    //Drink//    ||
  |  Toast  |  Coffee  |  Tea |

Finally, let's see and example of text alignment in cells:

 || Table Heading | Table Heading |
 |          Table |     align     |
 |          lines |      is       |
 |      with cell |     nice!     |

Images

Nested supports the inclusion of images, resize them and specify its position.

The use of the gallery assistant is highly recommended, it will take care of the filename format and copy of the image to the correct location. That is, when imported with the gallery assistant images will be transliterated and renamed to a Web safe name. Document images are saved to a folder called images that will be located aside the main (.t2t) document.

Example:

This is the Nested logo:

[logo.png]

The very same logo, but proportionally 
resized to 60px wide:

[60-logo.png]

Now, the key to position the image 
is the ratio between the right margin 
and left margin (right/left spaces):

- If ratio is the same, the image is 
  centered. This also apply to images
  without margin at all (like the above).
     [60-logo.png]     
% Note the same amount of spaces on the 
% right and left of the mark.
- If left margin is greater than the 
  right margin, then the image is right 
  aligned.
     [60-logo.png]
- If right margin is greater than the 
  left margin, then the image is left 
  aligned.
[60-logo.png]     
% Note the presence of several spaces on
% the right.


Easy, right?

Links

Nested supports internal links (a.k.a anchors), named links and automatic recognition of e-mail and internet addresses.

Any valid internet URL, ftp, news or e-mail address is detected and converted automatically. Links can be used with images too.

The use of the included assistant is recommended, in particular for the transliteration of the section name, but otherwise is not absolutely required.

Example:

The following internet address will be automatically 
recognized as such and thus is converted to a link:

- Visit the Nested website at 
http://nestededitor.sourceforge.net/.


Now, the same internet address but as a named link:

- Visit the Nested website 
[here http://nestededitor.sourceforge.net/].


Now, the same internet address but as an image link:

- Visit the Nested website 
[[60-logo.png] http://nestededitor.sourceforge.net/]


The following is an internal link pointing to the
//Keyboard shortcuts// section:

- After you learn the markup, visit the 
[Keyboard shortcuts #keyboard_shortcuts] section.


Finally, note that e-mails are automatically 
recognized too:

- If you have a problem, send your question to
nestededitor@googlegroups.com.

Footnotes

Footnotes in Nested are simple, you just need to include a special token to mark where a footnote should be placed. Then, anywhere in that section, preferably at the end of it, place the corresponding text and mark it with the token. Note that marks are interpreted sequentially, so the first mark will be associated with the first footnote text found, an so on. Also note, that if you want to have a multiline footnote you need to ident the following lines with exactly 4 spaces. On HTML target the footnotes will be added at the end of the section.

In summary, inserting a footnote is a process of two steps:

1. Place the footnote mark: °°_
2. Place the footnote text: _°°

Example:

Nested°°_ is a specialized editor focused on 
creating structured documents such as reports, 
publications, presentations, books, etc. It 
is designed to help the user concentrate on 
writing content without been distracted by 
format or markup. It offers a rich WYSIWYM°°_ 
interface where the user writes plain text 
with a lightweight markup language.

_°° Nested is a specialized editor 
    for structured documents. For 
    more information visit 
    http://nestededitor.sourceforge.net/.
_°° **WYSIWYM** : What You See Is What You Mean.
    See http://en.wikipedia.org/wiki/WYSIWYM.

Lines

Lines are used to separate sections or to differentiate parts of the content.

Example:

A separator line:
--------------------
And a stronger one:
====================
(At least 20 chars)

Macros

Macros are special purpose keywords, that are expanded on conversion time. They are used to insert dynamic information, for example the current date or the document table of contents.

A macro is represented by the %% chars followed by its name, such as %%date. Date macro do accept an optional formatting string inside parenthesis, right after the macro name, such as %%date(%Y-%m-%d). This format string mixes common text with special directives, identified by a percent sign % followed by an identification character. If no format string is given, the default format %Y%m%d is used. See http://docs.python.org/library/time.html for more information.

%%date

Insert the current date. The default format is %%date(%Y%m%d), which gives YYYYMMDD.

%%toc

Specifies where the Table of Contents will be placed. You can even use it multiple times. Note that you must also use the Table of Contents option in the document properties.

Example:

This is the Nested markup reference 
document. Last update was the 
**%%date(%Y-%m-%d %X)**.

Note: Currently, Nested supports only a subset of the macros provided by txt2tags. This limitation is because txt2tags is used as a module and not directly. Macros NOT supported by Nested are:

• %%mtime: The source file modification time.
• %%infile: The source file path.
• %%outfile: The output file path.

Filters

Nested has an advanced and powerful filter system. Filters can be explained as a "find and replace" function. Filters can be applied before or after the convertion of the source document. Filters applied before the convertion are called preproc (pre-processors) and those applied after the convertion are called postproc (post-processors).

Filters can be applied for a specific target, so you can have a filter for when you're publishing to HTML and another one that will be used when publishing to LaTeX.

To add a filter to your document open the document properties File > Properties. You can find on the left pane two inputs where you can write your filters, one is for preprocs and the other for postprocs. Filters syntax is:

%!type(target): 'find' 'replace'

• type is one of preproc or postproc
• target can be omitted, if present, it must be one of xhtmls (for HTML), tex (for LaTeX, PDF) or txt (for plain text).
• find can be any simple text or a Python regular expression.
  You can find complete information of Python regular expressions here and here.
• replace can be any simple text or a composite text that uses tokens found by the find regular expression.

For example:

%!preproc: 'MYWEBSITE' 'http://nestededitor.sourceforge.net/'
%!postproc(xhtmls): '(?i)(</?)b>' '\1strong>'
%!postproc(html): '<body.*?>' '<body style="background-color: green">'

Example:

Using the following preproc and postproc:

%!preproc: 'MYWEBSITE' 'http://nestededitor.sourceforge.net/'
%!postproc(xhtmls): '<div class="post-proc">' '<div style="background-color: lightBlue;">'

%html% ''' <div class="post-proc">

Nested is a specialized editor for 
structured documents. For more information
visit the project MYWEBSITE.

%html% ''' </div>

Note: preprocs and postprocs will process the entire document without considering blocks or markup. So verbatim blocks in particular, or any other markup, can be affected by the filter.

Keyboard shortcuts

Section management

Content formatting

Content edition

File management

Editor appearance