diff options
Diffstat (limited to 'docs/tool/Info/NDMarkup.txt')
| -rw-r--r-- | docs/tool/Info/NDMarkup.txt | 91 |
1 files changed, 91 insertions, 0 deletions
diff --git a/docs/tool/Info/NDMarkup.txt b/docs/tool/Info/NDMarkup.txt new file mode 100644 index 00000000..db1817af --- /dev/null +++ b/docs/tool/Info/NDMarkup.txt @@ -0,0 +1,91 @@ + + Architecture: NDMarkup +_______________________________________________________________________________ + +A markup format used by the parser, both internally and in <NaturalDocs::Parser::ParsedTopic> objects. Text formatted in +NDMarkup will only have the tags documented below. + + +About: Top-Level Tags + + All content will be surrounded by one of the top-level tags. These tags will not appear within each other. + + <p></p> - Surrounds a paragraph. Paragraph breaks will replace double line breaks, and single line breaks will + be removed completely. + + <code></code> - Surrounds code or text diagrams that should appear literally in the output. + + <h></h> - Surrounds a heading. + + <ul></ul> - Surrounds a bulleted (unordered) list. + <dl></dl> - Surrounds a description list, which is what you are reading. + + <img mode="inline" target="" original=""> - An inline image. Target contains the image target, and original contains the + original text in case it doesn't resolve. + + +About: List Item Tags + + These tags will only appear within their respective lists. + + <li></li> - Surrounds a bulleted list item. + <de></de> - Surrounds a description list entry, which is the left side. It will always be followed by a description list + description. + <ds></ds> - Surrounds a description list symbol. This is the same as a description list entry, except that the content + is also a referenceable symbol. This occurs when inside a list topic. This tag will always + be followed by a description list description. + <dd></dd> - Surrounds a description list description, which is the right side. It will always be preceded by a description + list entry or symbol. + +About: Text Tags + + These tags will only appear in paragraphs, headings, or description list descriptions. + + <b></b> - Bold + <i></i> - Italics + <u></u> - Underline + + <link target="" name="" original=""> - Surrounds a potential link to a symbol; potential because the target is not guaranteed to + exist. This tag merely designates an attempted link. Target is what is attempting to be + linked to, name is the text that should appear for a successful link, and original is the + original text in case the link doesn't resolve. + + <url target="" name=""> - An external link. There's no need for an original attribute because it will always be + turned into an actual link. + <email target="" name=""> - A link to an e-mail address. + + <img mode="link" target="" original=""> - An image link. Target contains the image target, and original contains the original + text in case it doesn't resolve. + + +About: Amp Chars + + These are the only amp chars supported, and will appear everywhere. Every other character will appear as is. + + & - The ampersand &. + " - The double quote ". + < - The less than sign <. + > - The greater than sign >. + +About: Tabs + + NDMarkup will not contain tab characters, only spaces. Any tab characters appearing in the source files will be + expanded/replaced as necessary. + + +About: General Tag Properties + + Since the tags are generated, they will always have the following properties, which will make pattern matching much + easier. + + - Tags and amp chars will always be in all lowercase. + - Properties will appear exactly as documented here. They will be in all lowercase, in the documented order, and will have no + extraneous whitespace. Anything appearing in the properties will have amp chars. + - All code is valid, meaning tags will always be closed, <li>s will only appear within <ul>s, etc. + + So, for example, you can match description list entries with /<de>(.+?)<\/de>/ and $1 will be the text. No surprises or + gotchas. No need for sophisticated parsing routines. + + Remember that for symbol definitions, the text should appear as is, but internally (such as for the anchor) they need to + be passed through <NaturalDocs::SymbolTable->Defines()> so that the output file is just as tolerant as + <NaturalDocs::SymbolTable>. |