forked from erlang/otp
/
README.md.txt
266 lines (189 loc) · 9.72 KB
/
README.md.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
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/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