aboutsummaryrefslogtreecommitdiffstats
path: root/HOWTO/MARKDOWN.md
diff options
context:
space:
mode:
Diffstat (limited to 'HOWTO/MARKDOWN.md')
-rw-r--r--HOWTO/MARKDOWN.md266
1 files changed, 266 insertions, 0 deletions
diff --git a/HOWTO/MARKDOWN.md b/HOWTO/MARKDOWN.md
new file mode 100644
index 0000000000..c9ad09a1be
--- /dev/null
+++ b/HOWTO/MARKDOWN.md
@@ -0,0 +1,266 @@
+Erlangish Markdown Text Files
+=============================
+
+Introduction
+------------
+
+If you are looking for information on how to build and install Erlang/OTP you
+want to read the [$ERL_TOP/HOWTO/INSTALL.md][] document instead of this document
+(where `$ERL_TOP` is the top source directory in the source tree).
+
+All files with the `.md` suffix (as well as this file) are ordinary text files
+written using a Markdown like notation, and can be read using an ordinary text
+editor such as for example `emacs`.
+
+This document describes how `*.md` files in the Erlang/OTP source tree should
+be written.
+
+> *NOTE*: Before modifying a `*.md` file read all of this document.
+
+Erlangish Markdown
+------------------
+
+We do not use Markdown straight out of the box. The Markdown syntax we use is
+similar to the original Markdown but with a number of tweaks. The original
+Markdown is documented at <http://daringfireball.net/projects/markdown/>. You
+should read that documentation as well as this document before modifying any
+Erlangish Markdown files in the Erlang/OTP source tree.
+
+The original Markdown syntax was designed for generating HTML code from an
+"easy to read/easy to write" plain text. Instead of generating HTML we generate
+XML that fits into our documentation, i.e. we generate Erlangish XML from
+Erlangish Markdown.
+
+The `.md` suffix has been chosen since [github][] will generate HTML pages for
+files with the `.md` suffix. Github does however not generate HTML according to
+Erlangish Markdown, so some features do not work. The Erlangish Markdown
+documents viewed at [our github repository][] will typically suffer from broken
+links. The original Markdown script, gitub's Markdown, and our Erlangish
+Markdown script will generate somewhat different results if you do not follow
+indentation rules outlined in the Markdown documentation. You are encouraged to
+try to write using a Markdown syntax that also looks nice on github. However,
+it is *much* more important that the document is formatted correct in the
+Erlang/OTP documentation.
+
+### Differences Between Markdown and Erlangish Markdown ###
+
+#### Missing Features ####
+
+This functionality is missing compared to Markdown version 1.0.1. Do not
+depend on the fact that these features are missing. Some of them might appear
+in the future.
+
+* No inline HTML. Currently no inline XML is allowed either. Inline XML might
+ be allowed in the future, but there is no real need for it since we use
+ Erlangish Markdown for "readme"s that have a main purpose of being readable
+ in plain text.
+
+* Backslash escapes all characters.
+
+* No support for "horizontal rules".
+
+* Links.
+ * No support for the "title" attribute.
+ * Automatic links does not support email addresses.
+
+* Images.
+ * No support for the "title" attribute. Specified "title" will however
+ be used as `<icaption>`.
+ * No support for the "alt" attribute.
+
+* Lists aren't supported inside block quotes.
+
+* Link and image definition names *are* case sensitive.
+
+#### Additional Features ####
+
+* Automatic anchors at each heading.
+
+* Optionally automatically generated table of contents.
+
+* Note blocks.
+
+* Warning blocks.
+
+#### Extra requirements ####
+
+* One and only one level 1 heading is allowed and required.
+
+* The level 1 heading must be the first heading in the document.
+
+* A level `X` heading must have a level `X-1` heading as parent heading.
+
+* Link and image definition names aren't allowed to begin with a
+ question mark (?) character. Names beginning with a question mark have
+ been reserved for other use.
+
+* The encoding of the file containing Erlangish Markdown should be
+ UTF-8.
+
+### Generated XML ###
+
+> *WARNING*: The `emd2exml` script will blindly generate XML code according
+> to the Erlangish Markdown in a file. Successfully generated XML does **not**
+> imply that the generated XML adheres to used DTDs. `emd2exml` does very
+> seldom fail and can easily generate XML that will cause the documentation
+> build to fail. You always have to keep in mind that the XML generated
+> should fit the chapter DTD of Erlang/OTP. Also note that even though HTML
+> generation succeeds the PDF generation might fail, etc.
+>
+> *Always build the Erlang/OTP documentation after modifying an Erlangish
+> Markdown document!*
+
+A note about how we talk about "tags" below. When we say "generate(s) `<X>`
+tags" this also imply that ending `</X>` tags will be generated at appropriate
+places. Appropriate attributes to the `X` tag will also be generated.
+
+* Inline and reference style links will either generate `<seealso>` tags
+ or `<url>` tags. If a "://" character sequence is found in the URL an
+ `<url>` tag will be generated; otherwise, a `<seealso>` tag is generated.
+
+* Automatic links will only generate `<url>` tags. This since a
+ "://" character sequence have to be present in the URL in order
+ for the link to be identified.
+
+* Inline and reference style images will generate a `<image file="...">
+ <icaption>...</icaption> </image>` sequence where the "title" will be
+ placed between `<icaption>` and `</icaption>`.
+
+* Block quotes generate `<blockquote>` tags.
+
+* If the first line of a top level block quote begins with a `> *NOTE*:`
+ character sequence, a `<note>` tag will be generated instead of a
+ `<blockquote>` tag. The note will span the entire block quote.
+
+* If the first line of a top level block quote begins with a `> *WARNING*:`
+ character sequence, a `<warning>` tag will be generated instead of a
+ `<blockquote>` tag. The warning will span the entire block quote.
+
+* Paragraphs will generate `<p>` tags.
+
+* Break line (double trailing white space) will generate `<br/>` tags.
+
+* An unordered list generates a `<list type="bulleted">` tag and `<item>`
+ tags for each item.
+
+* An ordered list generates a `<list type="ordered">` tag and `<item>` tags
+ for each item.
+
+* Code blocks will generate `<code type="none">` tags.
+
+* Code span (backticks) will generate `<c>` tags.
+
+* Emphasis (single `*` or `_`) will generate `<em>` tags.
+
+* Strong emphasis (double `*` or `_`) will generate `<b>` tags.
+
+* The level 1 heading will cause the following to be generated:
+
+ <?xml version="1.0" encoding="utf8" ?>
+ <!DOCTYPE chapter SYSTEM "chapter.dtd">
+ <chapter>
+ <header>
+ <copyright>
+ ...
+ </copyright>
+ <legalnotice>
+ ...
+ </legalnotice>
+
+ <title>...</title>
+ ...
+ <file>...</file>
+ </header>
+
+ ...
+
+ </chapter>
+
+ The content of copyright section and the legalnotice section will
+ contain information from a \%CopyrightBegin\%, \%CopyrightEnd\% block
+ if such exist (see below).
+
+* A level `X` heading where `1 < X <= 3` will cause the the following
+ to be generated:
+
+ <marker id="..."/>
+ <section>
+ <title>...</title>
+ ...
+ </section>
+
+ The marker id is automatically generated as a combination of all parent
+ headings up to and including level 2 separated by a `_` character. As in
+ `<marker heading 2>_<marker heading 3>_ ... _<current marker heading>`
+ where each "marker heading" is constructed as follows. All characters a-z
+ and A-Z are kept as they are, space and tab characters are replaced by
+ `-` characters, and all other characters are dropped.
+
+ This way it is relatively easy to make sure that all marker ids of a
+ document are unique, but there is of course no guarantee that they are.
+
+ The upside of these auto generated markers is that we wont have to clutter
+ the document with XML or something else while being able to refer into
+ the document. The downside is that if you change a level 2 heading you
+ change a lot of marker ids which may break links into a document from
+ other documents. That is, *be careful* when changing headings in an
+ existing document.
+
+* A level `X` heading where `3 < X` will cause the the following
+ to be generated:
+
+ <marker id="..."/>
+ <p><b>...</b></p>
+ ...
+
+ Current DTD:s used don't support deeper levels of sections, and we
+ therefore simulate a section this way. The marker id is generated as for
+ a true section (see above).
+
+* If a section enclosed by \%CopyrightBegin\% and \%CopyrightEnd\% is
+ encountered, it will be interpreted as an EPL copyright and license,
+ and will be used in the header section of the document. The
+ \%CopyrightBegin\% and \%CopyrightEnd\% "tags" will be removed from
+ the output.
+
+* All occurrences of \%OTP-REL% will be replaced by current release number
+ (e.g. R14A).
+
+* All occurrences of \%ERTS-VSN% will be replaced by current ERTS version
+ (e.g. 5.8).
+
+* Adding a `[?TOC]: true` line (optionally indented with three spaces)
+ anywhere in the document will cause a table of contents to be automatically
+ generated at the beginning of the generated document.
+
+* Unicode characters (encoded in UTF-8) are allowed and will be passed
+ through as is to the output file.
+
+Copyright and License
+---------------------
+
+%CopyrightBegin%
+
+Copyright Ericsson AB 2010-2013. All Rights Reserved.
+
+The contents of this file are subject to the Erlang Public License,
+Version 1.1, (the "License"); you may not use this file except in
+compliance with the License. You should have received a copy of the
+Erlang Public License along with this software. If not, it can be
+retrieved online at http://www.erlang.org/.
+
+Software distributed under the License is distributed on an "AS IS"
+basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+the License for the specific language governing rights and limitations
+under the License.
+
+%CopyrightEnd%
+
+
+
+ [$ERL_TOP/HOWTO/INSTALL.md]: INSTALL.md
+ [github]: http://github.com
+ [our github repository]: http://github.com/erlang/otp
+
+
+ [?TOC]: true