Header2

Highlighted text

Use simple html marking to <mark>highlight</mark>

Emphasized text

To emphasize some text, surround it with *s or _, like this:

This text is emphasized with underscores, and this is emphasized with asterisks.

Double * or _ produces strong emphasis:

This is strong emphasis and with underscores.

A * or _ character surrounded by spaces, or backslash-escaped, will not trigger emphasis:

This is * not emphasized *, and *neither is this*.

Because _ is sometimes used inside words and identifiers, pandoc does not interpret a _ surrounded by alphanumeric characters as an emphasis marker. If you want to emphasize just part of a word, use *:

feasible, not feasable.

Strikeout

This is deleted text.

Superscripts and subscripts

H₂O is a liquid. 2¹⁰ is 1024.

Comments

Use HTML-style comments <!-- ... --> to exclude pieces of documentation from output. No characters are allowed between start of line and <!--, as well as between --> and line end. Note that commented out sections will be deleted even from inside ``` ... ``` blocks.

<!--
  ...
  commented out part
  ...
-->

Tables

Simple tables can be created using markdown syntax as described here.

The alternative for markdown syntax for simple tables is Embedded CSV and TSV tables.

Embedded XLSX Sheet plugin allows inserting more complex tables with formatting, cell highlighting, column span, and so on.

Footnotes

Pandoc¹-style markdown footnotes² are supported³.

Math formulas

Markdown supports LaTeX-style syntax for rendering formulas. Good quick reference for the syntax here: http://meta.math.stackexchange.com/questions/5020/mathjax-basic-tutorial-and-quick-reference. There's also excellent app to identify TeX symbols from handwriting: http://detexify.kirelabs.org/classify.html - just scribble any symbol there and it will give you couple of variant to represent it in the formula. For more info, Google "latex formulas".

To insert a formula in line with the text, surround it in $ .. $, e.g.: $P_{total} = P_{leak} + C_{dyn} * V^2 * F$.

The result looks like this: \(P_{total} = P_{leak} + C_{dyn} * V^2 * F\).

To insert a formula centered on a separate line, surround it in $$ .. $$, e.g. $$\sum_{n=1}^{\infty} 2^{-n} = 1$$. Here's what the result looks like: \[\sum_{n=1}^{\infty} 2^{-n} = 1\]

Cross-References

### Numbered List {#explicit_reference}

Code Syntax Highlighting

BOARD_SIZE = 8

def under_attack(col, queens):
    left = right = col

    for r, c in reversed(queens):
        left, right = left - 1, right + 1

        if c in (left, col, right):
            return True
    return False

def solve(n):
    if n == 0:
        return [[]]

    smaller_solutions = solve(n - 1)

    return [solution+[(n,i+1)]
        for i in xrange(BOARD_SIZE)
            for solution in smaller_solutions
                if not under_attack(i+1, solution)]
for answer in solve(BOARD_SIZE):
    print answer

#include <stdio.h>
int main()
{
   // printf() displays the string inside quotation
   printf("C Programming");
   return 0;
}

text 
line 2

Inline Markdown Files

For large documents, it may be useful to compose text in several chapters and then merge them together in a master document. The tools support this using a unique tag indicating file insertion. This tag must be in the first column of the file (no spaces at the front of the line) and must refer to a valid markdown file (.md or.mmd). See the example below.

[_chapter1.md]

When this file is parsed, all section headings are adjusted so that it is nested within the current document. For example, if the current section heading level of this document is H3 (###), then all H1 (#) elements and text in the included file will be modified to be H4 (####). Raw text in the main body that is not under a heading will be inserted at the H3 level.

In many cases, when developing chapters, the user would like to put them together as isolated documents and rely on the build tools to stitch them together. Therefore, to differentiate a chapter from a normal document, we are using a simple underscore. If a document starts with an underscore, it will be excluded from the builds.

The following text is inserted by the tools as a nested chapter.

This paragraph was inserted from the requested chapter file

Inline H2

This is H2 in the inserted chapter file

Specifying max-width for plugin content

Most of the time default width/height generated by the tools for showing the plugin content works fine. Sometimes, however the result may look nicer if a particular diagram/drawing/etc. is constrained to a certain width. In this case, specifying max-width attribute is helpful:

```plugin("blah"){max-width: 600px}
...
```

The syntax for attribute specification is regular CSS style declaration. When it is specified, plugin generated content will be put inside a <div> element with specified style attributes.

Embedded Plantuml

Below is embedded plantuml sequence diagram. The syntax spec for plantuml can be found at plantuml.com.

Embedded Diagrams Through Ascii Art (ditaa)

You can embedded diagrams written in ASCII Art using ditaa. The syntax spec for ditaa can be found at ditaa website

Here is an example of a diagram using ditaa.

Block Diagram

Signal Interface Definition

Using the simple syntax provided below, you can develop some simple but effective diagrams to describe signal interfaces between two logic blocks. This plugin is called sigint.

Syntax is as follows. The 'clock' and 'power' tags are special. They are detected by looking for the exact syntax as show below. If found, they will be picked up and placed in the summary table.

sigint("Test Interface")
== srcip <- dstip: signame1
Markdown **description**
clock: dclk
power: vccs

== srcip -> dstip: signame2

== srcip <-> dstip: signame3
clock: aclk
power: vccp
This is an *example*

1. Item1
2. Item2

Test Interface

Embedded DOT / Graphviz

You can integrate dot diagrams as follows. It's super easy. The syntax spec for dot graphs can be found at graphviz.org.

Embedded Flow Chart diagrams

Flow charts can be embedded as follows. Syntax and examples can be found at http://flowchart.js.org.

Links in the diagrams are not enabled at the moment, as they are overridden by the zoom functionality.

Embedded Register Definitions

msb:lsb | field name | Description
msb:lsb | field name | Description
...
msb:lsb | field name | Description

---
Attribute1: Value
Attribute2: Value
...

== MSB:LSB | Field Name | Access Type | Reset Default
Description
Multi-line is OK.
Markdown is OK.

= 0 | Enum0
= 1 | Enum1

== MSB:LSB | Field Name | RO | 0x00
An example of a register bit that spans multiple bits (msb=lsb is also allowed)

== LSB | Field Name | RO | 0x00
An example of a register bit that has just a single bit
...

Embedded Packet Definitions

Also supported are packet data types

Embedded XLSX Sheet

This formatting:

xls("pm_doc_demo.xlsx", "Sheet name" [, "Title Override (optional)"])

Tells the tools to open crashlog.xlsx, grab the sheet ID named 'Sheet name', and insert its contents into the document. It will also automatically link the table to the original XLSX for further detailed review. If the optional title override is supplied, it will be used when displaying the table instead of the actual sheet name.

Footnotes may be added automatically to the spreadsheet by inserting comments in the cell in which you want a footnote attached. For example, see below a few footnotes automatically inserted from the excel spreadsheet's comments. Cross-reference hyperlinks are also included for easy navigation.

Embedded XLSX Image Snapshot

Ranges of cells from excel files can be embedded as pictures to preserve exact appearance as when viewed in Excel application.

Command Syntax:

xlsimg("filename.xlsx" [, sheet="Sheet name (optional)"] [, range="Range (optional)"] [, title="Title Override (optional)"])

Arguments:

• "Sheet name (optional)" - specifies sheet name to snapshot. If not supplied or equals "" and range doesn't specify the page either, first sheet will be selected.
• "Range (optional)" - Excel range to snapshot. Syntax is whatever Excel allows - see examples below. If not supplied or equals "", all used cells in a sheet are selected.
• "Title Override (optional)" - when supplied, will be used when displaying the table instead of the sheet name.

Example syntax:

xlsimg("test.xlsx", title="MyTitle")

xlsimg("test.xlsx", sheet="Sheet2", title="The Title")

xlsimg("test.xlsx", range="MyNamedRange")

xlsimg("test.xlsx", range="Sheet3!B5:C8")

xlsimg("test.xlsx", range="Sheet4!SheetScopedNamedRange")

Usage example:

xlsimg("pm_doc_demo.xlsx", range="SquaresAndCubes", title="Squares and Cubes")

Squares and Cubes

Embedded CSV and TSV tables

You can edit a table in excel, save as CSV, and use the csv import widget to import it into the final output. If the code block is empty, it will automatically look for a file to fill it.

You can also do a simple csv in text format using commas as a delimiter.

Commas in the data are accepted if they are escaped, '\,'.

Tab separated lists are also supported using the 'tsv' tag. For example.

Embedded VISIO Drawing

You can embed a tab in a visio document as a standalone picture.

Hyperlinks are also supported. They will be copied locally to the 'auto' directory and inserted as if they are locally managed in the repo. Note that this is just a snapshot, it will only update on a clean rebuild.

visio("filename", "Tab Name" [, "Title Name"][, format="png"])

By default, Visio diagrams will be converted to SVG (Scalable Vector Graphics) format, which allows to search text within the images and upscale the image without quality loss. However, for some Visio content (like embeddings from other Office tools) Visio SVG export may fail and output image will not be correct. In such cases user can specify format="png" switch so that Visio diagram will be converted to raster image instead of SVG, and should display exactly like in Visio (zoom and search ability will be lost for such diagram).

BKM: if visio diagram comes out too small, you can upscale it using {width: N px} syntax, similar to one described in Specifying max-width for plugin content, e.g.:

visio("filename", "Tab Name"){width: 800px}

Embedded Wavedrom Timing Diagram

For drawing timing diagrams, the wavedrom tool is very handy. See the wavedrom help documentation for proper syntax. You may integrate a raw wavedrom source input into the document and it will be rendered by the build tools and integrated as a figure similar to other figures.

For example, the below code:

{ signal: [
  {    name: 'clk',   wave: 'p..Pp..P'},
  ['Master',
    ['ctrl',
      {name: 'write', wave: '01.0....'},
      {name: 'read',  wave: '0...1..0'}
    ],
    {  name: 'addr',  wave: 'x3.x4..x', data: 'A1 A2'},
    {  name: 'wdata', wave: 'x3.x....', data: 'D1'   },
  ],
  {},
  ['Slave',
    ['ctrl',
      {name: 'ack',   wave: 'x01x0.1x'},
    ],
    {  name: 'rdata', wave: 'x.....4x', data: 'Q2'},
  ]
]}

Is rendered into this wavedrom output

# Waveform
clk   | p..Pp..P
      | .a......
write | 01.0....
read  | 0...1..0
addr  | x3.x4..x  | A1 A2
      | ....b...

wdata | x3.x....  | D1
ack   | x01x0.1x
      | ......c.
rdata | x.....4x  | Q2

# Edges / Arrows
a~>b This is an edge definition
b-|>c a sharp edge

# Config
hscale: 2

# Waveform
==== Source ====
clk   | p..Pp..P
      | .a......
write | 01.0....
read  | 0...1..0
addr  | x3.x4..x  | A1 A2
      | ....b...

____ Dest ____ 
wdata | x3.x....  | D1
ack   | x01x0.1x
      | ......c.
rdata | x.....4x  | Q2

# Edges / Arrows
a~>b This is an edge definition
b-|>c a sharp edge

# Config
hscale: 2

Embedded Schematic Diagram

For drawing circuit diagrams with the aid of ShemDraw, the following syntax can be used:

schemdraw("Diagram title")

For example, the below code:

d.add(e.GND)
d.add(e.SOURCE_V, label='$V_{OUT}$')
d.add(e.RES, label='$R_{AVP}$')
d.add(e.DOT); d.push()
rl1 = d.add(e.RES, d='up')
d.labelI(rl1, '$I_{load1}$')
d.pop()
rpp = d.add(e.RES)
rpp.add_label('$R_{pp}$', loc='bot')
d.labelI(rpp, '$I_{CROSS}$')
d.add(e.DOT); d.push()
rl2 = d.add(e.RES, d='up')
d.labelI(rl2, '$I_{load2}$', top=False)
d.pop()
d.add(e.RES, botlabel='$R_{AVP}$', d='down')
d.add(e.SOURCE_V, botlabel='$V_{OUT}+V_{ERR}$', reverse=True, d='down')
d.add(e.GND)

Is rendered into this schematic diagram:

Documentation for the syntax can be found at https://cdelker.bitbucket.io/SchemDraw/SchemDraw.html.

Under the hood, user-provided code is inserted in the following template and executed as a regular python program:

import SchemDraw as schem
import SchemDraw.elements as e
import SchemDraw.logic as l
d = schem.Drawing()
# ...
# Your code goes here
# ...
d.draw(showplot=False)
d.save("<image file name>")

Integrated XSD Documentation

For an XML schema that you wish to document, the build tools have automated flows for generating XSD schema specifications in a standard documentation template.

To embed documentation, implement code such as this:

xsd2html("assets\simple_schema.xsd", "Simple Schema")

The resulting code is a simple pointer to the documentation as well as a pointer to the original source file for the schema.

• Simple Schema (source)

Integrated Python Scripts

The 'python_run' plugin may be used to execute python code and generate output. The script is run standalone in a separate executable shell and the output is captured.

For example, the following code will produce a date string when embedded inside the python_run plugin block:

import time
print "*%s*" % time.strftime("%B %d, %Y")

The result is as follows:

November 18, 2017

import time
print "*%s*" % time.strftime("%B %d, %Y")

import time
print "*%s*" % time.strftime("%B %d, %Y")

*November 18, 2017*

valid_ratios = [8, 10, 12, 16] # defined by divider design

def ratio2divisor(ratio_req):
    # Input: 25MHz-based ratio
    # Output: (selected divisor, selected ratio)
    ratio_in = 1600 / 25 # Divider input frequency, in 25Mhz units (a constant)
    # Select valid ratio that is equal or higher than requested
    for r in valid_ratios:
        if r >= ratio_req:
            break
    divisor = ratio_in / r # integer division
    return (divisor, r)

Collecting OPENs/FIXMEs

The opens plugin allows to create lists of OPENs/FIXMEs/TODOs in the document. Here's the example of how it could be used:

# Items to close

```opens("OPEN")
```

# Required fixes

```opens("FIXME", numbered=True)
```

```opens("TODO", numbered=True)
```