aboutsummaryrefslogtreecommitdiffstats
path: root/README.md.txt
diff options
context:
space:
mode:
Diffstat (limited to 'README.md.txt')
-rw-r--r--README.md.txt266
1 files changed, 0 insertions, 266 deletions
diff --git a/README.md.txt b/README.md.txt
deleted file mode 100644
index a5a1bf4b7d..0000000000
--- a/README.md.txt
+++ /dev/null
@@ -1,266 +0,0 @@
-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/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. 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/INSTALL.md]: doc/installation_guide:INSTALL
- [github]: http://github.com
- [our github repository]: http://github.com/erlang/otp
-
-
- [?TOC]: true